Return to emacs.tex CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / emacs / man

Annotation of 43BSD/contrib/emacs/man/emacs.tex, revision 1.1

1.1     ! root        1: \input texinfo  @c -*-texinfo-*-
        !             2: @setfilename ../info/emacs
        !             3: @ifinfo
        !             4: This file documents the GNU Emacs editor.
        !             5: 
        !             6: Copyright (C) 1985 Richard M. Stallman.
        !             7: 
        !             8: Permission is granted to make and distribute verbatim copies of
        !             9: this manual provided the copyright notice and this permission notice
        !            10: are preserved on all copies.
        !            11: 
        !            12: @ignore
        !            13: Permission is granted to process this file through Tex and print the
        !            14: results, provided the printed document carries copying permission
        !            15: notice identical to this one except for the removal of this paragraph
        !            16: (this paragraph not being relevant to the printed manual).
        !            17: 
        !            18: @end ignore
        !            19: Permission is granted to copy and distribute modified versions of this
        !            20: manual under the conditions for verbatim copying, provided also that the
        !            21: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs
        !            22: General Public License'' are included exactly as in the original, and
        !            23: provided that the entire resulting derived work is distributed under the
        !            24: terms of a permission notice identical to this one.
        !            25: 
        !            26: Permission is granted to copy and distribute translations of this manual
        !            27: into another language, under the above conditions for modified versions,
        !            28: except that the sections entitled ``The GNU Manifesto'', ``Distribution''
        !            29: and ``GNU Emacs General Public License'' may be included in a translation
        !            30: approved by the author instead of in the original English.
        !            31: @end ifinfo
        !            32: @c
        !            33: @setchapternewpage odd
        !            34: @settitle GNU Emacs Manual
        !            35: @c
        !            36: @titlepage
        !            37: @sp 6
        !            38: @center @titlefont{GNU Emacs Manual}
        !            39: @sp 4
        !            40: @center Fourth Edition, Emacs Version 17
        !            41: @sp 1
        !            42: @center February 1986
        !            43: @sp 5
        !            44: @center Richard Stallman
        !            45: @page
        !            46: @vskip 0pt plus 1filll
        !            47: Copyright @copyright{} 1985 Richard M. Stallman.
        !            48: 
        !            49: Permission is granted to make and distribute verbatim copies of
        !            50: this manual provided the copyright notice and this permission notice
        !            51: are preserved on all copies.
        !            52: 
        !            53: Permission is granted to copy and distribute modified versions of this
        !            54: manual under the conditions for verbatim copying, provided also that the
        !            55: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU Emacs
        !            56: General Public License'' are included exactly as in the original, and
        !            57: provided that the entire resulting derived work is distributed under the
        !            58: terms of a permission notice identical to this one.
        !            59: 
        !            60: Permission is granted to copy and distribute translations of this manual
        !            61: into another language, under the above conditions for modified versions,
        !            62: except that the sections entitled ``The GNU Manifesto'', ``Distribution''
        !            63: and ``GNU Emacs General Public License'' may be included in a translation
        !            64: approved by the author instead of in the original English.
        !            65: @end titlepage
        !            66: @page
        !            67: @ifinfo
        !            68: @node Top, Distrib,, (DIR)
        !            69: 
        !            70: The Emacs Editor
        !            71: ****************
        !            72: 
        !            73: Emacs is the extensible, customizable, self-documenting real-time
        !            74: display editor.  This Info file describes how to edit with Emacs
        !            75: and some of how to customize it, but not how to extend it.
        !            76: 
        !            77: @end ifinfo
        !            78: @menu
        !            79: * Distrib::     How to get the latest Emacs distribution.
        !            80: * License::     The GNU Emacs General Public License gives you permission
        !            81:                to redistribute GNU Emacs on certain terms; and also
        !            82:                explains that there is no warranty.
        !            83: * Intro::       An introduction to Emacs concepts.
        !            84: * Glossary::    The glossary.
        !            85: * Manifesto::   What's GNU?  Gnu's Not Unix!
        !            86: 
        !            87: Indexes, nodes containing large menus
        !            88: * Key Index::      An item for each standard Emacs key sequence.
        !            89: * Command Index::  An item for each command name.
        !            90: * Variable Index:: An item for each documented variable.
        !            91: * Concept Index::  An item for each concept.
        !            92: 
        !            93: Important General Concepts
        !            94: * Screen::      How to interpret what you see on the screen.
        !            95: * Characters::  Emacs's character sets for file contents and for keyboard.
        !            96: * Keys::        Key sequences: what you type to request one editing action.
        !            97: * Commands::    Commands: named functions run by key sequences to do editing.
        !            98: * Entering Emacs::  Starting Emacs from the shell.
        !            99: * Exiting::     Stopping or killing Emacs.
        !           100: * Basic::       The most basic editing commands.
        !           101: * Undo::        Undoing recently made changes in the text.
        !           102: * Minibuffer::  Entering arguments that are prompted for.
        !           103: * M-x::         Invoking commands by their names.
        !           104: * Help::        Commands for asking Emacs about its commands.
        !           105: 
        !           106: Important Text-Changing Commands
        !           107: * Mark::        The mark: how to delimit a ``region'' of text.
        !           108: * Killing::     Killing text.
        !           109: * Yanking::     Recovering killed text.  Moving text.
        !           110: * Accumulating Text::
        !           111:                 Other ways of copying text.
        !           112: * Rectangles::  Operating on the text inside a rectangle on the screen.
        !           113: * Registers::   Saving a text string or a location in the buffer.
        !           114: * Display::     Controlling what text is displayed.
        !           115: * Search::      Finding or replacing occurrences of a string.
        !           116: * Fixit::       Commands especially useful for fixing typos.
        !           117: 
        !           118: Larger Units of Text
        !           119: * Files::       All about handling files.
        !           120: * Buffers::     Multiple buffers; editing several files at once.
        !           121: * Windows::     Viewing two pieces of text at once.
        !           122: 
        !           123: Advanced Features
        !           124: * Major Modes:: Text mode vs. Lisp mode vs. C mode ...
        !           125: * Indentation:: Editing the white space at the beginnings of lines.
        !           126: * Text::        Commands and modes for editing English.
        !           127: * Programs::    Commands and modes for editing programs.
        !           128: * Running::     Compiling, running and debugging programs.
        !           129: * Abbrevs::     How to define text abbreviations to reduce
        !           130:                  the number of characters you must type.
        !           131: * Picture::     Editing pictures made up of characters
        !           132:                  using the quarter-plane screen model.
        !           133: * Sending Mail::Sending mail in Emacs.
        !           134: * Rmail::       Reading mail in Emacs.
        !           135: * Recursive Edit::
        !           136:                 A command can allow you to do editing
        !           137:                  "within the command".  This is called a
        !           138:                  `recursive editing level'.
        !           139: * Narrowing::   Restricting display and editing to a portion
        !           140:                  of the buffer.
        !           141: * Shell::       Executing shell commands from Emacs.
        !           142: * Dissociated Press::  Dissociating text for fun.
        !           143: * Amusements::         Various games and hacks.
        !           144: * Customization::      Modifying the behavior of Emacs.
        !           145: 
        !           146: Recovery from Problems.
        !           147: * Quitting::    Quitting and aborting.
        !           148: * Lossage::     What to do if Emacs is hung or malfunctioning.
        !           149: * Bugs::        How and when to report a bug.
        !           150: 
        !           151: Here are some other nodes which are really inferiors of the ones
        !           152: already listed, mentioned here so you can get to them in one step:
        !           153: 
        !           154: Subnodes of Screen
        !           155: * Point::      The place in the text where editing commands operate.
        !           156: * Echo Area::   Short messages appear at the bottom of the screen.
        !           157: * Mode Line::  Interpreting the mode line.
        !           158: 
        !           159: Subnodes of Basic
        !           160: * Blank Lines:: Commands to make or delete blank lines.
        !           161: * Continuation Lines:: Lines too wide for the screen.
        !           162: * Position Info::      What page, line, row, or column is point on?
        !           163: * Arguments::   Giving numeric arguments to commands.
        !           164: 
        !           165: Subnodes of Minibuffer
        !           166: * Minibuffer File::    Entering file names with the minibuffer.
        !           167: * Minibuffer Edit::    How to edit in the minibuffer.
        !           168: * Completion::  An abbreviation facility for minibuffer input.
        !           169: * Repetition::  Re-executing previous commands that used the minibuffer.
        !           170: 
        !           171: Subnodes of Mark
        !           172: * Mark Ring::   Previous mark positions saved so you can go back there.
        !           173: 
        !           174: Subnodes of Registers
        !           175: * RegPos::      Saving positions in registers.
        !           176: * RegText::     Saving text in registers.
        !           177: * RegRect::     Saving rectangles in registers.
        !           178: 
        !           179: Subnodes of Display
        !           180: * Selective Display::      Hiding lines with lots of indentation.
        !           181: * Display Vars::           Information on variables for customizing display.
        !           182: 
        !           183: Subnodes of Search
        !           184: * Incremental Search::     Search happens as you type the string.
        !           185: * Nonincremental Search::  Specify entire string and then search.
        !           186: * Word Search::           Search for sequence of words.
        !           187: * Regexp Search::         Search for match for a regexp.
        !           188: * Regexps::               Syntax of regular expressions.
        !           189: * Search Case::                   To ignore case while searching, or not.
        !           190: * Replace::               Search, and replace some or all matches.
        !           191: * Unconditional Replace::  Everything about replacement except for querying.
        !           192: * Query Replace::          How to use querying.
        !           193: * Other Repeating Search:: Operating on all matches for some regexp.
        !           194: 
        !           195: Subnodes of Fixit
        !           196: * Kill Errors:: Commands to kill a batch of recently entered text.
        !           197: * Transpose::   Exchanging two characters, words, lines, lists...
        !           198: * Fixing Case:: Correcting case of last word entered.
        !           199: * Spelling::    Apply spelling checker to a word, or a whole file.
        !           200: 
        !           201: Subnodes of Files
        !           202: * File Names::  How to type and edit file name arguments.
        !           203: * Visiting::    Visiting a file prepares Emacs to edit the file.
        !           204: * Saving::      Saving makes your changes permanent.
        !           205: * Backup::      How Emacs saves the old version of your file.
        !           206: * Interlocking::How Emacs protects against simultaneous editing
        !           207:                  of one file by two users.
        !           208: * Reverting::   Reverting cancels all the changes not saved.
        !           209: * Auto Save::   Auto Save periodically protects against loss of data.
        !           210: * ListDir::     Listing the contents of a file directory.
        !           211: * Dired::       ``Editing'' a directory to delete, rename, etc.
        !           212:                  the files in it.
        !           213: * Misc File Ops:: Other things you can do on files.
        !           214: 
        !           215: Subnodes of Buffers
        !           216: * Select Buffer::   Creating a new buffer or reselecting an old one.
        !           217: * List Buffers::    Getting a list of buffers that exist.
        !           218: * Misc Buffer::     Renaming; changing read-only status.
        !           219: * Kill Buffer::     Killing buffers you no longer need.
        !           220: * Several Buffers:: How to go through the list of all buffers
        !           221:                      and operate variously on several of them.
        !           222: 
        !           223: Subnodes of Indentation
        !           224: * Indentation Commands:: Various commands and techniques for indentation.
        !           225: * Tab Stops::   You can set arbitrary "tab stops" and then
        !           226:                  indent to the next tab stop when you want to.
        !           227: * Just Spaces:: You can request indentation using just spaces.
        !           228: 
        !           229: Subnodes of Text
        !           230: * Text Mode::   The major mode for editing text files.
        !           231: * Nroff Mode::  The major mode for editing input to the formatter nroff.
        !           232: * TeX Mode::    The major mode for editing input to the formatter TeX.
        !           233: * Outline Mode::The major mode for editing outlines.
        !           234: * Words::       Moving over and killing words.
        !           235: * Sentences::   Moving over and killing sentences.
        !           236: * Paragraphs:: Moving over paragraphs.
        !           237: * Pages::      Moving over pages.
        !           238: * Filling::     Filling or justifying text
        !           239: * Case::        Changing the case of text
        !           240: 
        !           241: Subnodes of Programs
        !           242: * Program Modes::       Major modes for editing programs.
        !           243: * Lists::       Expressions with balanced parentheses.
        !           244:                  There are editing commands to operate on them.
        !           245: * Defuns::      Each program is made up of separate functions.
        !           246:                  There are editing commands to operate on them.
        !           247: * Grinding::    Adjusting indentation to show the nesting.
        !           248: * Matching::    Insertion of a close-delimiter flashes matching open.
        !           249: * Comments::    Inserting, illing and aligning comments.
        !           250: * Balanced Editing::    Inserting two matching parentheses at once, etc.
        !           251: * Documentation::       Getting documentation of functions you plan to call.
        !           252: * Change Log::  Maintaining a change history for your program.
        !           253: * Tags::        Go direct to any function in your program in one
        !           254:                  command.  Tags remembers which file it is in.
        !           255: 
        !           256: Subnodes of Running
        !           257: * Compilation::       Compiling programs in languages other than Lisp
        !           258:                        (C, Pascal, etc.)
        !           259: * Lisp Modes::        Various modes for editing Lisp programs, with
        !           260:                        different facilities for running the Lisp programs.
        !           261: * Lisp Libraries::    Creating Lisp programs to run in Emacs.
        !           262: * Lisp Interaction::  Executing Lisp in an Emacs buffer.
        !           263: * Lisp Eval::         Executing a single Lisp expression in Emacs.
        !           264: * Lisp Debug::        Debugging Lisp programs running in Emacs.
        !           265: * External Lisp::     Communicating through Emacs with a separate Lisp.
        !           266: 
        !           267: Subnodes of Abbrevs
        !           268: * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
        !           269: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
        !           270: * Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
        !           271: * Saving Abbrevs::    Saving the entire list of abbrevs for another session.
        !           272: 
        !           273: Subnodes of Picture
        !           274: * Basic Picture::     Basic concepts and simple commands of Picture Mode.
        !           275: * Insert in Picture:: Controlling direction of cursor motion
        !           276:                        after "self-inserting" characters.
        !           277: * Tabs in Picture::   Various features for tab stops and indentation.
        !           278: * Rectangles in Picture:: Clearing and superimposing rectangles.
        !           279: 
        !           280: Subnodes of Rmail::
        !           281: * Rmail Scrolling::   Scrolling through a message.
        !           282: * Rmail Motion::      Moving to another message.
        !           283: * Rmail Deletion::    Deleting and expunging messages.
        !           284: * Rmail Inbox::       How mail gets into the Rmail file.
        !           285: * Rmail Files::       Using multiple Rmail files.
        !           286: * Rmail Labels::      Classifying messages by labeling them.
        !           287: * Rmail Summary::     Summaries show brief info on many messages.
        !           288: * Rmail Reply::       Sending replies to messages you are viewing.
        !           289: * Rmail Editing::     Editing message text and headers in Rmail.
        !           290: * Rmail Digest::      Extracting the messages from a digest message.
        !           291: 
        !           292: Subnodes of Customization
        !           293: * Minor Modes::       Each minor mode is one feature you can turn on
        !           294:                        independently of any others.
        !           295: * Variables::         Many Emacs commands examine Emacs variables
        !           296:                        to decide what to do; by setting variables,
        !           297:                        you can control their functioning.
        !           298: * Examining::         Examining or setting one variable's value.
        !           299: * Edit Options::      Examining or editing list of all variables' values.
        !           300: * Locals::            Per-buffer values of variables.
        !           301: * File Variables::    How files can specify variable values.
        !           302: * Keyboard Macros::   A keyboard macro records a sequence of keystrokes
        !           303:                        to be replayed with a single command.
        !           304: * Key Bindings::      The keymaps say what command each key runs.
        !           305:                        By changing them, you can "redefine keys".
        !           306: * Keymaps::           Definition of the keymap data structure.
        !           307: * Rebinding::         How to redefine one key's meaning conveniently.
        !           308: * Disabling::         Disabling a command means confirmation is required
        !           309:                        before it can be executed.  This is done to protect
        !           310:                        beginners from surprises.
        !           311: * Syntax::            The syntax table controls how words and expressions
        !           312:                        are parsed.
        !           313: * Init File::         How to write common customizations in the `.emacs' file.
        !           314: 
        !           315: Subnodes of Lossage (and recovery)
        !           316: * Stuck Recursive::   `[...]' in mode line around the parentheses.
        !           317: * Screen Garbled::    Garbage on the screen.
        !           318: * Text Garbled::      Garbage in the text.
        !           319: * Unasked-for Search::Spontaneous entry to incremental search.
        !           320: * Emergency Escape::  Emergency escape---
        !           321:                        What to do if Emacs stops responding.
        !           322: * Total Frustration:: When you are at your wits' end.
        !           323: @end menu
        !           324: 
        !           325: @iftex
        !           326: @unnumbered Preface
        !           327: 
        !           328:   This manual documents the use and simple customization of the
        !           329: Emacs editor.  The reader is not expected to be a programmer.  Even simple
        !           330: customizations do not require programming skill, but the user who is not
        !           331: interested in customizing can ignore the scattered customization hints.
        !           332: 
        !           333:   This is primarily a reference manual, but can also be used as a
        !           334: primer.  However, I recommend that the newcomer first use the on-line,
        !           335: learn-by-doing tutorial, which you get by running Emacs and typing
        !           336: @kbd{C-h t}.  With it, you learn Emacs by using Emacs on a specially
        !           337: designed file which describes commands, tells you when to try them,
        !           338: and then explains the results you see.  This gives a more vivid
        !           339: introduction than a printed manual.
        !           340: 
        !           341:   On first reading, you need not make any attempt to memorize chapters one
        !           342: and two, which describe the notational conventions of the manual and the
        !           343: general appearance of the Emacs display screen.  It is enough to be aware
        !           344: of what questions are answered in these chapters, so you can refer back
        !           345: when you later become interested in the answers.  After reading chapter
        !           346: four you should practice the commands there.  The next few chapters
        !           347: describe fundamental techniques and concepts that are referred to again and
        !           348: again.  It is best to understand them thoroughly, experimenting with them
        !           349: if necessary.
        !           350: 
        !           351:   To find the documentation on a particular command, look in the
        !           352: index.  Keys (character commands) and command names have separate
        !           353: indexes just for them.  There is also a glossary, with a cross
        !           354: reference for each term.
        !           355: 
        !           356: @ignore
        !           357:   If you know vaguely what the command
        !           358: does, look in the command summary.  The command summary contains a line or
        !           359: two about each command, and a cross reference to the section of the
        !           360: manual that describes the command in more detail; related commands
        !           361: are grouped together.
        !           362: @end ignore
        !           363: 
        !           364:   This manual comes in two forms: the published form and the Info form.
        !           365: The Info form is for on-line perusal with the INFO program; it is
        !           366: distributed along with GNU Emacs.  Both forms contain substantially the
        !           367: same text and are generated from a common source file, which is distributed
        !           368: along with GNU Emacs.
        !           369: 
        !           370:   GNU Emacs is a member of the Emacs editor family.  There are many Emacs
        !           371: editors, all sharing common principles of organization.  For information on
        !           372: the underlying philosophy of Emacs and the lessons learned from its
        !           373: development, write for a copy of AI memo 519a, ``Emacs, the Extensible,
        !           374: Customizable Self-Documenting Display Editor'', to
        !           375: 
        !           376: @display
        !           377: Publications Department
        !           378: Artificial Intelligence Lab
        !           379: 545 Tech Square
        !           380: Cambridge, MA 02139
        !           381: @end display
        !           382: 
        !           383: At last report they charge $2.25 per copy.
        !           384: @end iftex
        !           385: 
        !           386: @node Distrib, License, Top, Top
        !           387: @unnumbered Distribution
        !           388: 
        !           389: GNU Emacs is @dfn{free}; this means that everyone is free to use it and
        !           390: free to redistribute it on a free basis.  GNU Emacs is not in the public
        !           391: domain; it is copyrighted and there are restrictions on its distribution,
        !           392: but these restrictions are designed to permit everything that a good
        !           393: cooperating citizen would want to do.  What is not allowed is to try to
        !           394: prevent others from further sharing any version of GNU Emacs that they
        !           395: might get from you.  The precise conditions are found in the GNU Emacs
        !           396: General Public License that comes with Emacs and also appears following
        !           397: this section.
        !           398: 
        !           399: The easiest way to get a copy of GNU Emacs is from someone else who has it.
        !           400: You need not ask for permission to do so, or tell any one else; just copy
        !           401: it.
        !           402: 
        !           403: If you have access to the Internet, you can get the latest distribution
        !           404: version of GNU Emacs from host @file{prep.ai.mit.edu} using anonymous
        !           405: login.  See the file @file{/u2/emacs/GETTING.GNU.SOFTWARE} on that host
        !           406: to find out about your options for copying and which files to use.
        !           407: 
        !           408: You may also eventually receive GNU Emacs when you buy a computer.
        !           409: Computer manufacturers are free to distribute copies on the same terms that
        !           410: apply to everyone else.  These terms require them to give you the full
        !           411: sources, including whatever changes they may have made, and to permit you
        !           412: to redistribute the GNU Emacs received from them under the usual terms of
        !           413: the General Public License.  In other words, the program must be free for
        !           414: you when you get it, not just free for the manufacturer.
        !           415: 
        !           416: If you cannot get a copy in any of those ways, you can order one from the
        !           417: Free Software Foundation.  Though Emacs itself is free, our distribution
        !           418: service is not.  An order form is included at the end of the manual, in
        !           419: manuals printed by the Foundation.  It is also included in the file
        !           420: @file{etc/DISTRIB} in the Emacs distribution.  For further information,
        !           421: write to
        !           422: 
        !           423: @display
        !           424: Free Software Foundation
        !           425: 1000 Mass Ave
        !           426: Cambridge, MA 02138
        !           427: @end display
        !           428: 
        !           429: The income from distribution fees goes to support the foundation's
        !           430: purpose: the development of more free software to distribute just like
        !           431: GNU Emacs.
        !           432: 
        !           433: If you find GNU Emacs useful, we urge you to @b{send a donation} to the Free
        !           434: Software Foundation.  This will help support development of the rest of the
        !           435: GNU system, and other useful software beyond that.  Subject to approval of
        !           436: our application for a tax exemption, your donation will be tax deductible.
        !           437: 
        !           438: @node License, Intro, Distrib, Top
        !           439: @unnumbered GNU Emacs General Public License
        !           440: 
        !           441:   The license agreements of most software companies keep you at the
        !           442: mercy of those companies.  By contrast, our general public license is
        !           443: intended to give everyone the right to share GNU Emacs.  To make
        !           444: sure that you get the rights we want you to have, we need to make
        !           445: restrictions that forbid anyone to deny you these rights or to ask you
        !           446: to surrender the rights.  Hence this license agreement.
        !           447: 
        !           448:   Specifically, we want to make sure that you have the right to give
        !           449: away copies of Emacs, that you receive source code or else can get it
        !           450: if you want it, that you can change Emacs or use pieces of it in new
        !           451: free programs, and that you know you can do these things.
        !           452: 
        !           453:   To make sure that everyone has such rights, we have to forbid you to
        !           454: deprive anyone else of these rights.  For example, if you distribute
        !           455: copies of Emacs, you must give the recipients all the rights that you
        !           456: have.  You must make sure that they, too, receive or can get the
        !           457: source code.  And you must tell them their rights.
        !           458: 
        !           459:   Also, for our own protection, we must make certain that everyone
        !           460: finds out that there is no warranty for GNU Emacs.  If Emacs is
        !           461: modified by someone else and passed on, we want its recipients to know
        !           462: that what they have is not what we distributed, so that any problems
        !           463: introduced by others will not reflect on our reputation.
        !           464: 
        !           465:   Therefore we (Richard Stallman and the Free Software Foundation, Inc.)@:
        !           466: make the following terms which say what you must do to be allowed to
        !           467: distribute or change GNU Emacs.
        !           468: 
        !           469: @unnumberedsec Copying Policies
        !           470: 
        !           471: @enumerate
        !           472: @item
        !           473: You may copy and distribute verbatim copies of GNU Emacs source
        !           474: code as you receive it, in any medium, provided that you conspicuously
        !           475: and appropriately publish on each file a valid copyright notice such
        !           476: as ``Copyright @copyright{} 1985 Richard M. Stallman'', containing the year of
        !           477: last change and name of copyright holder for the file in question;
        !           478: keep intact the notices on all files that refer to this License
        !           479: Agreement and to the absence of any warranty; and give any other
        !           480: recipients of the GNU Emacs program a copy of this License Agreement
        !           481: along with the program.
        !           482: 
        !           483: @item
        !           484: You may modify your copy or copies of GNU Emacs source code or
        !           485: any portion of it, and copy and distribute such modifications under
        !           486: the terms of Paragraph 1 above, provided that you also do the following:
        !           487: 
        !           488: @enumerate
        !           489: @item
        !           490: cause the modified files to carry prominent notices stating
        !           491: who last changed such files and the date of any change; and
        !           492: 
        !           493: @item
        !           494: cause the whole of any work that you distribute or publish,
        !           495: that in whole or in part contains or is a derivative of GNU Emacs
        !           496: or any part thereof, to be freely distributed
        !           497: and licensed to all third parties on terms identical to those
        !           498: contained in this License Agreement (except that you may choose
        !           499: to grant more extensive warranty protection to third parties,
        !           500: at your option).
        !           501: 
        !           502: @item
        !           503: if the modified program serves as a text editor, cause it
        !           504: when started running in the simplest and usual way, to print
        !           505: an announcement including a valid copyright notice (``Copyright
        !           506: @copyright{}'', the year of authorship, and all copyright owners' names),
        !           507: saying that there is no warranty (or else, saying that you provide
        !           508: a warranty) and that users may redistribute the program under
        !           509: these conditions, and telling the user how to view a copy of
        !           510: this License Agreement.
        !           511: @end enumerate
        !           512: 
        !           513: @item
        !           514: You may copy and distribute GNU Emacs or any portion of it in
        !           515: compiled, executable or object code form under the terms of Paragraphs
        !           516: 1 and 2 above provided that you do the following:
        !           517: 
        !           518: @enumerate
        !           519: @item
        !           520: cause each such copy of GNU Emacs to be accompanied by the
        !           521: corresponding machine-readable source code; or
        !           522: 
        !           523: @item
        !           524: cause each such copy of GNU Emacs to be accompanied by a written
        !           525: offer, with no time limit, to give any third party free (except
        !           526: for a nominal shipping charge) machine readable copy of the
        !           527: corresponding source code; or
        !           528: 
        !           529: @item
        !           530: in the case of a recipient of GNU Emacs in compiled, executable
        !           531: or object code form (without the corresponding source code) you
        !           532: shall cause copies you distribute to be accompanied by a copy of
        !           533: the written offer of source code which you received along with
        !           534: the copy of GNU Emacs.
        !           535: @end enumerate
        !           536: 
        !           537: @item
        !           538: You may not copy, sublicense, distribute or transfer GNU Emacs except
        !           539: as expressly provided under this License Agreement.  Any attempt
        !           540: otherwise to copy, sublicense, distribute or transfer GNU Emacs is
        !           541: void and your rights to use GNU Emacs under this License agreement
        !           542: shall be automatically terminated.  However, parties who have received
        !           543: computer software programs from you with this License Agreement will
        !           544: not have their licenses terminated so long as such parties remain in
        !           545: full compliance.
        !           546: @end enumerate
        !           547: 
        !           548: Your comments and suggestions about our licensing policies and our
        !           549: software are welcome!  Please contact the Free Software Foundation, Inc.,
        !           550: 1000 Mass Ave, Cambridge, MA 02138, or call (617) 876-3296.
        !           551: 
        !           552: @iftex
        !           553: @vfil
        !           554: @eject
        !           555: @end iftex
        !           556: @unnumberedsec NO WARRANTY
        !           557: 
        !           558:   BECAUSE GNU EMACS IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
        !           559: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
        !           560: WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
        !           561: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU EMACS ``AS IS''
        !           562: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
        !           563: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
        !           564: FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY
        !           565: AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE GNU EMACS
        !           566: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
        !           567: SERVICING, REPAIR OR CORRECTION.
        !           568: 
        !           569:  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
        !           570: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
        !           571: MODIFY AND REDISTRIBUTE GNU EMACS AS PERMITTED ABOVE, BE LIABLE TO YOU
        !           572: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
        !           573: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
        !           574: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
        !           575: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
        !           576: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
        !           577: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
        !           578: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
        !           579: OTHER PARTY.
        !           580: 
        !           581: @node Intro, Glossary, License, Top
        !           582: @unnumbered Introduction
        !           583: 
        !           584:   You are about to read about GNU Emacs, the Unix/GNU incarnation of the
        !           585: advanced, self-documenting, customizable, extensible real-time display
        !           586: editor Emacs.  (The `G' in `GNU' is not silent.)
        !           587: 
        !           588:   We say that Emacs is a @dfn{display} editor because normally the text
        !           589: being edited is visible on the screen and is updated automatically as you
        !           590: type your commands.  @xref{Screen,Display}.
        !           591: 
        !           592:   We call it a @dfn{real-time} editor because the display is updated very
        !           593: frequently, usually after each character or pair of characters you
        !           594: type.  This minimizes the amount of information you must keep in your
        !           595: head as you edit.  @xref{Basic,Real-time,Basic Editing}.
        !           596: 
        !           597:   We call Emacs advanced because it provides facilities that go beyond
        !           598: simple insertion and deletion: filling of text; automatic indentation of
        !           599: programs; viewing two or more files at once; and dealing in terms of
        !           600: characters, words, lines, sentences, paragraphs, and pages, as well as
        !           601: expressions and comments in several different programming languages.  It is
        !           602: much easier to type one command meaning ``go to the end of the paragraph''
        !           603: than to find that spot with simple cursor keys.
        !           604: 
        !           605:   @dfn{Self-documenting} means that at any time you can type a special
        !           606: character, @kbd{Control-h}, to find out what your options are.  You can
        !           607: also use it to find out what any command does, or to find all the commands
        !           608: that pertain to a topic.  @xref{Help}.
        !           609: 
        !           610:   @dfn{Customizable} means that you can change the definitions of Emacs
        !           611: commands in little ways.  For example, if you use a programming language in
        !           612: which comments start with @samp{<**} and end with @samp{**>}, you can tell
        !           613: the Emacs comment manipulation commands to use those strings
        !           614: (@pxref{Comments}).  Another sort of customization is rearrangement of the
        !           615: command set.  For example, if you prefer the four basic cursor motion
        !           616: commands (up, down, left and right) on keys in a diamond pattern on the
        !           617: keyboard, you can have it.  @xref{Customization}.
        !           618: 
        !           619:   @dfn{Extensible} means that you can go beyond simple customization and
        !           620: write entirely new commands, programs in the Lisp language to be run by
        !           621: Emacs's own Lisp interpreter.  Emacs is an ``on-line extensible'' system,
        !           622: which means that it is divided into many functions that call each other,
        !           623: any of which can be redefined in the middle of an editing session.  Any
        !           624: part of Emacs can be replaced without making a separate copy of all of
        !           625: Emacs.  Most of the editing commands of Emacs are written in Lisp already;
        !           626: the few exceptions could have been written in Lisp but are written in C for
        !           627: efficiency.  Although only a programmer can write an extension, anybody can
        !           628: use it afterward.
        !           629: 
        !           630: @node Screen, Characters, Concept Index, Top
        !           631: 
        !           632: @chapter The Organization of the Screen
        !           633: @cindex screen
        !           634: 
        !           635:   Emacs divides the screen into several areas, each of which contains
        !           636: its own sorts of information.  The biggest area, of course, is the one
        !           637: in which you usually see the text you are editing.
        !           638: 
        !           639:   When you are using Emacs, the screen is divided into a number of
        !           640: @dfn{windows}.  Initially there is one text window occupying all but the
        !           641: last line, plus the special @dfn{echo area} or @dfn{minibuffer window} in
        !           642: the last line.  The text window can be subdivided horizontally or
        !           643: vertically into multiple text windows, each of which can be used for a
        !           644: different file (@pxref{Windows}).  The window that the cursor is in is the
        !           645: @dfn{selected window}, in which editing takes place.  The other windows are
        !           646: just for reference unless you select one of them.
        !           647: 
        !           648:   Each text window's last line is a @dfn{mode line} which describes what is
        !           649: going on in that window.  It is in inverse video if the terminal supports
        !           650: that, and contains text that starts like @samp{-----Emacs:@: @var{something}}.  Its
        !           651: purpose is to indicate what buffer is being displayed in the window above
        !           652: it; what major and minor modes are in use; and whether the buffer's text
        !           653: has been changed.
        !           654: 
        !           655: @menu
        !           656: * Point::      The place in the text where editing commands operate.
        !           657: * Echo Area::   Short messages appear at the bottom of the screen.
        !           658: * Mode Line::  Interpreting the mode line.
        !           659: @end menu
        !           660: 
        !           661: @node Point, Echo Area, Screen, Screen
        !           662: @section Point
        !           663: @cindex point
        !           664: @cindex cursor
        !           665: 
        !           666:   When Emacs is running, the terminal's cursor shows the location at
        !           667: which editing commands will take effect.  This location is called
        !           668: @dfn{point}.  Other commands move point through the text, so that you
        !           669: can edit at different places in it.
        !           670: 
        !           671:   While the cursor appears to point @var{at} a character, point should be
        !           672: thought of as @var{between} two characters; it points @var{before} the character
        !           673: that the cursor appears on top of.  Sometimes people speak of ``the
        !           674: cursor'' when they mean ``point'', or speak of commands that move point as
        !           675: ``cursor motion'' commands.
        !           676: 
        !           677:   Terminals have only one cursor, and when output is in progress it must
        !           678: appear where the typing is being done.  This does not mean that point is
        !           679: moving.  It is only that Emacs has no way to show you the location of point
        !           680: except when the terminal is idle.
        !           681: 
        !           682:   Each Emacs buffer has its own point location.  A buffer that is not being
        !           683: displayed remembers where point is so that it can be seen when you look at
        !           684: that buffer again.
        !           685: 
        !           686:   When there are multiple text windows, each window has its own point
        !           687: location.  The cursor shows the location of point in the selected window.
        !           688: This also is how you can tell which window is selected.  If the same buffer
        !           689: appears in more than one window, point can be moved in each window
        !           690: independently.
        !           691: 
        !           692:   The term `point' comes from the character @samp{.}, which was the
        !           693: command in TECO (the language in which the original Emacs was written)
        !           694: for accessing the value now called `point'.
        !           695: 
        !           696: @node Echo Area, Mode Line, Point, Screen
        !           697: @section The Echo Area
        !           698: @cindex echo area
        !           699: 
        !           700:   The line at the bottom of the screen (below the mode line) is the
        !           701: @dfn{echo area}.  It is used to display small amounts of text for several
        !           702: purposes.
        !           703: 
        !           704:   @dfn{Echoing} means printing out the characters that you type.  Emacs
        !           705: does not echo single-character keys, and does not echo any keys if you type
        !           706: the characters with no long pause, but if you pause for more than a second
        !           707: in the middle of a multi-character key, then all the characters typed so
        !           708: far are echoed.  This is intended to @dfn{prompt} you for the rest of the
        !           709: key.  Once the beginning of a key has been echoed, all the rest is echoed
        !           710: as soon as it is typed; so either the entire key or none of it is echoed.
        !           711: This behavior is designed to give confident users fast response, while
        !           712: giving hesitant users maximum feedback.  This behavior is controlled by a
        !           713: variable you can change (@pxref{Display Vars}).
        !           714: 
        !           715:   If a command cannot be executed, it may print an @dfn{error message} in
        !           716: the echo area.  Error messages are accompanied by a beep or by flashing the
        !           717: screen.  Also, any input you have typed ahead is thrown away when an error
        !           718: happens.
        !           719: 
        !           720:   Some commands print informative messages in the echo area.  These
        !           721: messages look much like error messages, but they are not announced with a
        !           722: beep and do not throw away input.  Sometimes the message tells you what the
        !           723: command has done, when it is not obvious from looking at the text being
        !           724: edited.  Sometimes the sole purpose of a command is to print a message
        !           725: giving you specific information.  For example, the command @kbd{C-x =} is
        !           726: used to print a message describing the character position of point in the
        !           727: text and its current column in the window.  Commands that take a long time
        !           728: often display messages ending in @samp{@dots{}} while they are working, and
        !           729: add @samp{done} at the end when they are finished.
        !           730: 
        !           731:   The echo area is also used to display the @dfn{minibuffer}, a window that
        !           732: is used for reading arguments to commands, such as the name of a file to be
        !           733: edited.  When the minibuffer is in use, the echo area begins with a prompt
        !           734: string that ends with a colon; also, the cursor appears in that line
        !           735: because it is the selected window.  You can always get out of the
        !           736: minibuffer by typing @kbd{C-g}.  @xref{Minibuffer}.
        !           737: 
        !           738: @node Mode Line,, Echo Area, Screen
        !           739: @section The Mode Line
        !           740: @cindex mode line
        !           741: @cindex top level
        !           742: 
        !           743:   Each text window's last line is a @dfn{mode line} which describes what is
        !           744: going on in that window.  When there is only one text window, the mode line
        !           745: appears right above the echo area.  The mode line is in inverse video if
        !           746: the terminal supports that, starts and ends with dashes, and contains text
        !           747: like @samp{Emacs:@: @var{something}}.
        !           748: 
        !           749:   If a mode line has something else in place of @samp{Emacs:@: @var{something}},
        !           750: then the window above it is in a special subsystem such as Rmail.  The mode
        !           751: line then indicates the status of the subsystem.
        !           752: 
        !           753:   Normally, the mode line has the following appearance:
        !           754: 
        !           755: @example
        !           756: --@var{ch}-Emacs: @var{buf}      (@var{major} @var{minor})----@var{pos}------
        !           757: @end example
        !           758: 
        !           759: @noindent
        !           760: This serves to indicate various information about the buffer being
        !           761: displayed in the window: the buffer's name, what major and minor modes are
        !           762: in use, whether the buffer's text has been changed, and how far down the
        !           763: buffer you are currently looking.  The top level mode line has this format:
        !           764: 
        !           765:   @var{ch} contains two stars @samp{**} if the text in the buffer has been
        !           766: edited (the buffer is ``modified''), or @samp{--} if the buffer has not been
        !           767: edited.  Exception: for a read-only buffer, it is @samp{%%}.
        !           768: 
        !           769:   @var{buf} is the name of the window's chosen @dfn{buffer}.  The chosen buffer
        !           770: in the selected window (the window that the cursor is in) is also Emacs's
        !           771: selected buffer, the one that editing takes place in.  When we speak of
        !           772: what some command does to ``the buffer'', we are talking about the
        !           773: currently selected buffer.  @xref{Buffers}.
        !           774: 
        !           775:   @var{major} is the name of the @dfn{major mode} in effect in the buffer.  At
        !           776: any time, each buffer is in one and only one of the possible major modes.
        !           777: The major modes available include Fundamental mode (the least specialized),
        !           778: Text mode, Lisp mode, C mode, and others.  @xref{Major Modes}, for details
        !           779: of how the modes differ and how to select one.@refill
        !           780: 
        !           781:   @var{minor} is a list of some of the @dfn{minor modes} that are turned on
        !           782: at the moment in the window's chosen buffer.  @samp{Fill} means that Auto
        !           783: Fill mode is on.  @samp{Abbrev} means that Word Abbrev mode is on.
        !           784: @samp{Overwrite} means that Overwrite mode is on.  @xref{Minor Modes}, for
        !           785: more information.  @samp{Narrow} means that the buffer being displayed has
        !           786: editing restricted to only a portion of its text.  This is not really a
        !           787: minor mode, but is like one.  @xref{Narrowing}.@refill
        !           788: 
        !           789:   @var{pos} tells you whether there is additional text above the top of the
        !           790: screen, or below the bottom.  If your file is small and it is all on the
        !           791: screen, @var{pos} is @samp{All}.  Otherwise, it is @samp{Top} if you are
        !           792: looking at the beginning of the file, @samp{Bot} if you are looking at the
        !           793: end of the file, or @samp{@var{nn}%}, where @var{nn} is the percentage of
        !           794: the file above the top of the screen.@refill
        !           795: 
        !           796:   Some other information about the state of Emacs can also be displayed
        !           797: among the minor modes.  @samp{Def} means that a keyboard macro is being
        !           798: defined; although this is not exactly a minor mode, it is still useful to
        !           799: be reminded about.  @xref{Keyboard Macros}.
        !           800: 
        !           801:   In addition, if Emacs is currently inside a recursive editing level,
        !           802: square brackets (@samp{[@dots{}]}) appear around the parentheses that
        !           803: surround the modes.  If Emacs is in one recursive editing level within
        !           804: another, double square brackets appear, and so on.  Since this information
        !           805: pertains to Emacs in general and not to any one buffer, the square brackets
        !           806: appear in every mode line on the screen or not in any of them.
        !           807: @xref{Recursive Edit}.@refill
        !           808: 
        !           809: @findex display-time
        !           810:   Emacs can optionally display the time and system load in all mode lines.
        !           811: To enable this feature, type @kbd{M-x display-time}.  The information added
        !           812: to the mode line usually appears after the file name, before the mode names
        !           813: and their parentheses.  It looks like this:
        !           814: 
        !           815: @example
        !           816: @var{hh}:@var{mm}pm @var{l.ll} [@var{d}]
        !           817: @end example
        !           818: 
        !           819: @noindent
        !           820: @var{hh} and @var{mm} are the hour and minute, followed always by @samp{am}
        !           821: or @samp{pm}.  @var{l.ll} is the average number of running processes in the
        !           822: whole system recently.  @var{d} is an approximate index of the ratio of
        !           823: disk activity to cpu activity for all users.
        !           824: 
        !           825: The word @samp{Mail} appears after the load level if there is mail for
        !           826: you that you have not read yet.
        !           827: 
        !           828: @vindex mode-line-inverse-video
        !           829:   Customization note: the variable @code{mode-line-inverse-video} controls
        !           830: whether the mode line is displayed in inverse video (assuming the terminal
        !           831: supports it); @code{nil} means no inverse video.  The default is @code{t}.
        !           832: 
        !           833: @iftex
        !           834: @chapter Characters, Keys and Commands
        !           835: 
        !           836:   This chapter explains the character set used by Emacs for input commands
        !           837: and for the contents of files, and also explains the concepts of
        !           838: @dfn{keys} and @dfn{commands} which are necessary for understanding how
        !           839: your keyboard input is understood by Emacs.
        !           840: @end iftex
        !           841: 
        !           842: @node Characters, Keys, Screen, Top
        !           843: @section The Emacs Character Set
        !           844: @cindex character set
        !           845: @cindex ASCII
        !           846: 
        !           847:   GNU Emacs uses the ASCII character set, which defines 128 different
        !           848: character codes.  Some of these codes are assigned graphic symbols such
        !           849: as @samp{a} and @samp{=}; the rest are control characters, such as
        !           850: @kbd{Control-a} (also called @kbd{C-a} for short).  @kbd{C-a} gets its name
        !           851: from the fact that you type it by holding down the @key{CTRL} key and
        !           852: then pressing @kbd{a}.  There is no distinction between @kbd{C-a} and
        !           853: @kbd{C-A}; they are the same character.@refill
        !           854: 
        !           855:   Some control characters have special names, and special keys you can
        !           856: type them with: @key{RET}, @key{TAB}, @key{LFD}, @key{DEL} and @key{ESC}.
        !           857: The space character is usually referred to below as @key{SPC}, even though
        !           858: strictly speaking it is a graphic character whose graphic happens to be
        !           859: blank.@refill
        !           860: 
        !           861:   Emacs extends the 7-bit ASCII code to an 8-bit code by adding an extra
        !           862: bit to each character.  This makes 256 possible command characters.  The
        !           863: additional bit is called Meta.  Any ASCII character can be made Meta;
        !           864: examples of Meta characters include @kbd{Meta-a} (@kbd{M-a}, for short),
        !           865: @kbd{M-A} (not the same character as @kbd{M-a}, but those two characters
        !           866: normally have the same meaning in Emacs), @kbd{M-@key{RET}}, and
        !           867: @kbd{M-C-a}.  For traditional reasons, @kbd{M-C-a} is usually called
        !           868: @kbd{C-M-a}; logically speaking, the order in which the modifier keys
        !           869: @key{CTRL} and @key{META} are mentioned does not matter.@refill
        !           870: 
        !           871: @cindex Control
        !           872: @cindex Meta
        !           873: @cindex C-
        !           874: @cindex M-
        !           875:   Some terminals have a @key{META} key, and allow you to type Meta
        !           876: characters by holding this key down.  Thus, @kbd{Meta-a} is typed by
        !           877: holding down @key{META} and pressing @kbd{a}.  Such a key is not always
        !           878: labeled @key{META}, however, as it is usually a special option from the
        !           879: manufacturer.  If there is no @key{META} key, you can still type Meta
        !           880: characters using two-character sequences starting with @key{ESC}.  Thus, to
        !           881: enter @kbd{M-a}, you could type @kbd{@key{ESC} a}.  To enter @kbd{C-M-a},
        !           882: you would type @kbd{@key{ESC} C-a}.  @key{ESC} is allowed on terminals with
        !           883: Meta keys, too, in case you have formed a habit of doing it.@refill
        !           884: 
        !           885: @vindex meta-flag
        !           886:   Emacs believes the terminal has a @key{META} key if the variable
        !           887: @code{meta-flag} is non-@code{nil}.  Normally this is set automatically
        !           888: according to the termcap entry for your terminal type.  However, sometimes
        !           889: the termcap entry is wrong, and then it is useful to set this variable
        !           890: yourself.
        !           891: 
        !           892:   Emacs buffers also use an 8-bit character set, because bytes have 8 bits,
        !           893: but only the ASCII characters are considered meaningful.  ASCII graphic
        !           894: characters in Emacs buffers are displayed with their graphics.  @key{LFD}
        !           895: is the same as a newline character; it is displayed by starting a new line.
        !           896: @key{TAB} is displayed by moving to the next tab stop column (usually every
        !           897: 8 columns).  Other control characters are displayed as a caret (@samp{^})
        !           898: followed by the non-control version of the character; thus, @kbd{C-a} is
        !           899: displayed as @samp{^A}.  Non-ASCII characters 128 and up are displayed with
        !           900: octal escape sequences; thus, character code 243 (octal), also called
        !           901: @kbd{M-#} when used as an input character, is displayed as @samp{\243}.
        !           902: 
        !           903: @node Keys, Commands, Characters, Top
        !           904: @section Keys
        !           905: 
        !           906: @cindex key
        !           907:   A @dfn{key}---short for @dfn{key sequence}---is a sequence of characters
        !           908: that is all part of specifying a single Emacs command to be run.  If the
        !           909: characters are enough to specify a command, they form a @dfn{complete key}.
        !           910: 
        !           911: @kindex C-c
        !           912: @kindex C-x
        !           913: @kindex C-h
        !           914: @kindex ESC
        !           915:   A single character is always a key; whether it is complete depends on its
        !           916: meaning in Emacs.  Most single characters are complete Emacs commands.
        !           917: @kbd{C-c}, @kbd{C-h}, @kbd{C-x} and @key{ESC} are the only ones that are not complete.
        !           918: 
        !           919: @cindex prefix key
        !           920:   A sequence of characters that is not enough to specify an Emacs command
        !           921: is called a @dfn{prefix key}.  A prefix key is the beginning of a series of
        !           922: longer sequences that are valid keys; adding any single character to the
        !           923: end of the prefix gives a valid key, which could be defined as an Emacs
        !           924: command.  For example, @kbd{C-x} is normally defined as a prefix, so
        !           925: @kbd{C-x} and the next input character combine to make a two-character key.
        !           926: There are 256 different two-character keys starting with @kbd{C-x}, one for
        !           927: each possible second character.  Many of these two-character keys starting
        !           928: with @kbd{C-x} are standardly defined as Emacs commands.  Notable examples
        !           929: include @kbd{C-x C-f} and @kbd{C-x s} (@pxref{Files}).
        !           930: 
        !           931:   Adding one character to a prefix key does not have to form a complete
        !           932: key.  It could make another, longer prefix.  For example, @kbd{C-x 4} is
        !           933: itself a prefix that leads to 256 different three-character keys, including
        !           934: @kbd{C-x 4 f}, @kbd{C-x 4 b} and so on.  It would be possible to define one
        !           935: of those three-character sequences as a prefix, creating a series of
        !           936: four-character keys, but we did not define any of them this way.
        !           937: 
        !           938:   All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
        !           939: @kbd{C-x 4}, and @key{ESC}.  But this is not built in; it is just a matter
        !           940: of Emacs's standard key bindings.  In customizing Emacs, you could make
        !           941: new prefix keys, or eliminate these.  @xref{Key Bindings}.
        !           942: 
        !           943: @node Commands, Entering Emacs, Keys, Top
        !           944: @section Keys and Commands
        !           945: 
        !           946: @cindex binding
        !           947: @cindex customization
        !           948: @cindex keymap
        !           949: @cindex function
        !           950: @cindex command
        !           951:   This manual is full of passages that tell you what particular keys do.
        !           952: But Emacs does not assign meanings to keys directly.  Instead, Emacs
        !           953: assigns meanings to @dfn{functions}, and then gives keys their meanings by
        !           954: @dfn{binding} them to functions. 
        !           955: 
        !           956:   A function is a Lisp object that can be executed as a program.
        !           957: Usually it is a Lisp symbol which has been given a function definition;
        !           958: every symbol has a name, usually made of a few English words separated by
        !           959: dashes, such as @code{next-line} or @code{forward-word}.  It also has a
        !           960: @dfn{definition} which is a Lisp program; this is what makes the function
        !           961: do what it does.  Only some functions can be the bindings of keys; these
        !           962: are functions whose definitions use @code{interactive} to specify how to
        !           963: call them interactively.  Such functions are called @dfn{commands}, and
        !           964: the name of a symbol that is a command is called a @dfn{command name}.
        !           965: More information on this subject will appear in the @i{GNU Emacs Lisp
        !           966: Manual} (which is not yet written).
        !           967: 
        !           968:   The bindings between keys and functions are recorded in various tables
        !           969: called @dfn{keymaps}.  @xref{Keymaps}.
        !           970: 
        !           971:   When we say that ``@kbd{C-n} moves down vertically one line'' we are
        !           972: glossing over a distinction that is irrelevant in ordinary use but is vital
        !           973: in understanding how to customize Emacs.  It is the function
        !           974: @code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
        !           975: this effect @i{because} it is bound to that function.  If you rebind
        !           976: @kbd{C-n} to the function @code{forward-word} then @kbd{C-n} will move
        !           977: forward by words instead.  Rebinding keys is a common method of
        !           978: customization.@refill
        !           979: 
        !           980:   In the rest of this manual, we usually ignore this subtlety to keep
        !           981: things simple.  To give the customizer the information he needs, we
        !           982: state the name of the command which really does the work in parentheses
        !           983: after mentioning the key that runs it.  For example, we will say that
        !           984: ``The command @kbd{C-n} (@code{next-line}) moves point vertically down,''
        !           985: meaning that @code{next-line} is a command that moves vertically down
        !           986: and @kbd{C-n} is a key that is standardly bound to it.
        !           987: 
        !           988: @cindex variables
        !           989:   While we are on the subject of customization information which you should
        !           990: not be frightened of, it's a good time to tell you about @dfn{variables}.
        !           991: Often the description of a command will say, ``To change this, set the
        !           992: variable @code{mumble-foo}.''  A variable is a name used to remember a
        !           993: value.  Most of the variables documented in this manual exist just to
        !           994: permit customization: the variable's value is examined by some command,
        !           995: and changing the value makes the command behave differently.  Until you
        !           996: are interested in customizing,  you can ignore this information.  When you
        !           997: are ready to be interested, read the basic information on variables, and
        !           998: then the information on individual variables will make sense.
        !           999: @xref{Variables}.
        !          1000: 
        !          1001: @node Entering Emacs, Exiting, Commands, Top
        !          1002: @chapter Entering and Exiting Emacs
        !          1003: @cindex entering Emacs
        !          1004: @cindex arguments (from shell)
        !          1005: 
        !          1006:   The simplest way to invoke Emacs is just to type @kbd{emacs @key{RET}}
        !          1007: at the shell.
        !          1008: 
        !          1009:   It is also possible to specify files to be visited, Lisp files to be
        !          1010: loaded, and functions to be called, by giving Emacs arguments in the
        !          1011: shell command line.  The command arguments are processed in the order they
        !          1012: appear in the command argument list; however, certain arguments must be at
        !          1013: the front of the list (@samp{-t} or @samp{-batch}) if they are used.
        !          1014: 
        !          1015:   Here are the arguments allowed:
        !          1016: 
        !          1017: @table @samp
        !          1018: @item @var{file}
        !          1019: Visit @var{file} using @code{find-file}.  @xref{Visiting}.
        !          1020: 
        !          1021: @item +@var{linenum} @var{file}
        !          1022: Visit @var{file} using @code{find-file}, then go to line number
        !          1023: @var{linenum} in it.
        !          1024: 
        !          1025: @item -l @var{file}
        !          1026: Load a file @var{file} of Lisp code with @code{load}.  @xref{Lisp
        !          1027: Libraries}.
        !          1028: 
        !          1029: @item -f @var{function}
        !          1030: Call Lisp function @var{function} with no arguments.
        !          1031: 
        !          1032: @item -kill
        !          1033: Exit from Emacs without asking for confirmation.
        !          1034: @end table
        !          1035: 
        !          1036:   The remaining switches are recognized only at the beginning of the
        !          1037: command line.  If more than one of them appears, they must appear in the
        !          1038: order that they appear in this table.
        !          1039: 
        !          1040: @table @samp
        !          1041: @item -t @var{device}
        !          1042: Use @var{device} as the terminal for editing input and output.
        !          1043: 
        !          1044: @cindex batch mode
        !          1045: @item -batch
        !          1046: Run Emacs in @dfn{batch mode}, which means that the text being edited is
        !          1047: not displayed and the standard Unix interrupt characters such as @kbd{C-z}
        !          1048: and @kbd{C-c} continue to have their normal effect.  Emacs in batch mode
        !          1049: outputs to @code{stdout} only what would normally be printed in the echo
        !          1050: area under program control.
        !          1051: 
        !          1052: Batch mode is used for running programs written in Emacs Lisp from
        !          1053: shell scripts, makefiles, and so on.  Normally the @samp{-l} switch
        !          1054: or @samp{-f} switch will be used as well, to invoke a Lisp program
        !          1055: to do the batch processing.
        !          1056: 
        !          1057: @samp{-batch} implies @samp{-q} (do not load an init file).  It also causes
        !          1058: Emacs to kill itself after all command switches have been processed.  In
        !          1059: addition, auto-saving is not done except in buffers for which it has been
        !          1060: explicitly requested.
        !          1061: 
        !          1062: @item -q
        !          1063: Do not load your Emacs init file @file{~/.emacs}.
        !          1064: 
        !          1065: @item -u @var{user}
        !          1066: Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
        !          1067: your own.
        !          1068: @end table
        !          1069: 
        !          1070:   One way to use command switches is to visit many files automatically:
        !          1071: 
        !          1072: @example
        !          1073: emacs *.c
        !          1074: @end example
        !          1075: 
        !          1076: @noindent
        !          1077: passes each @code{.c} file as a separate argument to Emacs, so that Emacs
        !          1078: visits each file (@pxref{Visiting}).
        !          1079:   
        !          1080:   Here is an advanced example that assumes you have a Lisp program
        !          1081: file called @file{hack-c-program.el} which, when loaded, performs some
        !          1082: useful operation on current buffer, expected to be a C program.
        !          1083: 
        !          1084: @example
        !          1085: emacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
        !          1086: @end example
        !          1087: 
        !          1088: @noindent
        !          1089: Here Emacs is told to visit @file{foo.c}, load @file{hack-c-program.el}
        !          1090: (which makes changes in the visited file), save @file{foo.c} (note that
        !          1091: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
        !          1092: then exit to the shell that this command was done with.  @samp{-batch}
        !          1093: guarantees there will be no problem redirecting output to @file{log},
        !          1094: because Emacs will not assume that it has a display terminal to work with.
        !          1095: 
        !          1096: @node Exiting, Basic, Entering Emacs, Top
        !          1097: @section Exiting Emacs
        !          1098: @cindex exiting
        !          1099: @cindex killing Emacs
        !          1100: @cindex suspending
        !          1101: 
        !          1102:   There are two commands for exiting Emacs because there are two kinds of
        !          1103: exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs.  @dfn{Suspending} means
        !          1104: stopping Emacs temporarily and returning control to its superior (usually
        !          1105: the shell), allowing you to resume editing later in the same Emacs job,
        !          1106: with the same files, same kill ring, same undo history, and so on.  This is
        !          1107: the usual way to exit.  @dfn{Killing} Emacs means destroying the Emacs job.
        !          1108: You can run Emacs again after killing it, but you will get a fresh Emacs;
        !          1109: there is no way to resume the same editing session after it has been
        !          1110: killed.
        !          1111: 
        !          1112: @kindex C-z
        !          1113: @findex suspend-emacs
        !          1114:   To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}).  On systems that do not
        !          1115: permit programs to be suspended, @kbd{C-z} runs an inferior shell that
        !          1116: communicates directly with the terminal, and Emacs waits until you exit
        !          1117: the subshell.  The only way on these systems to get back to the shell from
        !          1118: which Emacs was run (to log out, for example) is to kill Emacs.  @kbd{C-d} or
        !          1119: @code{exit} are typical commands to exit a subshell.  
        !          1120: 
        !          1121: @kindex C-x C-c
        !          1122: @findex save-buffers-kill-emacs
        !          1123:   To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}).  A
        !          1124: two-character key is used for this to make it harder to type.  Unless a
        !          1125: numeric argument is used, this command first offers to save any modified
        !          1126: buffers.  If you do not save them all, it asks for reconfirmation with
        !          1127: `yes' before killing Emacs, since any changes not saved before that will be
        !          1128: lost forever.  Also, if any subprocesses are still running, @kbd{C-x C-c}
        !          1129: asks for confirmation about them, since killing Emacs will kill the
        !          1130: subprocesses immediately.
        !          1131: 
        !          1132:   In most programs running on Berkeley Unix, @b{but not in Emacs}, the
        !          1133: characters @kbd{C-z} and @kbd{C-c} instantly suspend or kill, respectively.
        !          1134: The meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired
        !          1135: by the standard Unix meanings of @kbd{C-z} and @kbd{C-c}, but there is no
        !          1136: causal connection.  The standard Berkeley Unix handling of @kbd{C-z} and
        !          1137: @kbd{C-c} is turned off in Emacs.  You could customize these keys to do
        !          1138: anything (@pxref{Keymaps}).
        !          1139: 
        !          1140: @c??? What about system V here?
        !          1141: 
        !          1142: @node Basic, Undo, Exiting, Top
        !          1143: @chapter Basic Editing Commands
        !          1144: 
        !          1145: @kindex C-h t
        !          1146: @findex help-with-tutorial
        !          1147:   We now give the basics of how to enter text, make corrections, and
        !          1148: save the text in a file.  If this material is new to you, you might
        !          1149: learn it more easily by running the Emacs learn-by-doing tutorial.  To
        !          1150: do this, type @kbd{Control-h t} (@code{help-with-tutorial}).
        !          1151: 
        !          1152: @section Inserting Text
        !          1153: 
        !          1154: @cindex insertion
        !          1155: @cindex point
        !          1156: @cindex cursor
        !          1157: @cindex graphic characters
        !          1158:   To insert printing characters into the text you are editing, just
        !          1159: type them.  Except in special modes, Emacs defines each printing
        !          1160: character as a key to run the command @code{self-insert}, which inserts
        !          1161: the character that you typed to invoke it into the buffer at the
        !          1162: cursor (that is, at @dfn{point}; @pxref{Point}).  The cursor moves
        !          1163: forward.  Any characters after the cursor move forward too.  If the
        !          1164: text in the buffer is @samp{FOOBAR}, with the cursor before the
        !          1165: @samp{B}, then if you type @kbd{XX}, you get @samp{FOOXXBAR}, with the
        !          1166: cursor still before the @samp{B}.
        !          1167: 
        !          1168: @kindex DEL
        !          1169: @cindex deletion
        !          1170: @findex delete-backward-char
        !          1171:    To @dfn{delete} text you have just inserted, you can use @key{DEL}
        !          1172: (which runs the command named @code{delete-backward-char}).  @key{DEL}
        !          1173: deletes the character @var{before} the cursor (not the one that the cursor
        !          1174: is on top of or under; that is the character @var{after} the cursor).  The
        !          1175: cursor and all characters after it move backwards.  Therefore, if you type
        !          1176: a printing character and then type @key{DEL}, they cancel out.
        !          1177: 
        !          1178: @kindex RET
        !          1179: @findex newline
        !          1180: @cindex newline
        !          1181:    To end a line and start typing a new one, type @key{RET} (running the
        !          1182: command @code{newline}).  @key{RET} operates by inserting a newline
        !          1183: character in the buffer.  If point is in the middle of a line, @key{RET}
        !          1184: splits the line.  Typing @key{DEL} when the cursor is at the beginning of a
        !          1185: line rubs out the newline before the line, thus joining the line with the
        !          1186: preceding line.
        !          1187: 
        !          1188: @cindex quoting
        !          1189: @kindex C-q
        !          1190: @findex quoted-insert
        !          1191:   Direct insertion works for printing characters and @key{SPC}, but other
        !          1192: characters act as editing commands and do not insert themselves.  If you
        !          1193: need to insert a control character or a character whose code is above 200
        !          1194: octal, you must @dfn{quote} it by typing @kbd{Control-q} (@code{quoted-insert}) first.
        !          1195: There are two ways to use @kbd{C-q}:
        !          1196: 
        !          1197: @itemize @bullet
        !          1198: @item
        !          1199: @kbd{Control-q} followed by any non-graphic character (even @kbd{C-g})
        !          1200: inserts that character.
        !          1201: @item
        !          1202: @kbd{Control-q} followed by three octal digits inserts the character
        !          1203: with the specified character code.
        !          1204: @end itemize
        !          1205: 
        !          1206: @noindent
        !          1207: A numeric argument to @kbd{C-q} specifies how many copies of the
        !          1208: quoted character should be inserted (@pxref{Arguments}).
        !          1209: 
        !          1210: @section Changing the Location of Point
        !          1211: 
        !          1212:   To do more than insert characters, you have to know how to move
        !          1213: point (@pxref{Point}).  Here are a few of the commands for doing that.
        !          1214: 
        !          1215: @kindex C-a
        !          1216: @kindex C-e
        !          1217: @kindex C-f
        !          1218: @kindex C-b
        !          1219: @kindex C-n
        !          1220: @kindex C-p
        !          1221: @kindex C-l
        !          1222: @kindex C-t
        !          1223: @kindex M->
        !          1224: @kindex M-<
        !          1225: @findex beginning-of-line
        !          1226: @findex end-of-line
        !          1227: @findex forward-char
        !          1228: @findex backward-char
        !          1229: @findex next-line
        !          1230: @findex previous-line
        !          1231: @findex recenter
        !          1232: @findex transpose-chars
        !          1233: @findex beginning-of-buffer
        !          1234: @findex end-of-buffer
        !          1235: @findex goto-char
        !          1236: @table @kbd
        !          1237: @item C-a
        !          1238: Move to the beginning of the line (@code{beginning-of-line}).
        !          1239: @item C-e
        !          1240: Move to the end of the line (@code{end-of-line}).
        !          1241: @item C-f
        !          1242: Move forward one character (@code{forward-char}).
        !          1243: @item C-b
        !          1244: Move backward one character (@code{backward-char}).
        !          1245: @item C-n
        !          1246: Move down one line, vertically (@code{next-line}).  This command
        !          1247: attempts to keep the horizontal position unchanged, so if you start in
        !          1248: the middle of one line, you end in the middle of the next.  When on
        !          1249: the last line of text, @kbd{C-n} creates a new line and moves onto it.
        !          1250: @item C-p
        !          1251: Move up one line, vertically (@code{previous-line}).
        !          1252: @item C-l
        !          1253: Clear the screen and reprint everything (@code{recenter}).
        !          1254: @item C-t
        !          1255: Transpose two characters, the ones before and after the cursor
        !          1256: (@code{transpose-chars}).
        !          1257: @item M-<
        !          1258: Move to the top of the buffer (@code{beginning-of-buffer}).  With
        !          1259: numeric argument @var{n}, move to @var{n}/10 of the way from the top.
        !          1260: @xref{Arguments}, for more information on numeric arguments.@refill
        !          1261: @item M->
        !          1262: Move to the end of the buffer (@code{end-of-buffer}).
        !          1263: @item M-x goto-char
        !          1264: Read a number @var{n} and move cursor to character number @var{n}.
        !          1265: Position 1 is the beginning of the buffer.
        !          1266: @item M-x goto-line
        !          1267: Read a number @var{n} and move cursor to line number @var{n}.  Line 1
        !          1268: is the beginning of the buffer.
        !          1269: @item C-x C-n
        !          1270: Use the current column of point as the @dfn{semipermanent goal column} for
        !          1271: @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}).  Henceforth, those
        !          1272: commands always move to this column in each line moved into, or as
        !          1273: close as possible given the contents of the line.  This goal column remains
        !          1274: in effect until canceled.
        !          1275: @item C-u C-x C-n
        !          1276: Cancel the goal column.  Henceforth, @kbd{C-n} and @kbd{C-p} once
        !          1277: again try to avoid changing the horizontal position, as usual.
        !          1278: @end table
        !          1279: 
        !          1280: @vindex track-eol
        !          1281:   If you set the variable @code{track-eol} to a non-@code{nil} value, then
        !          1282: @kbd{C-n} and @kbd{C-p} when at the end of the starting line move to the
        !          1283: end of the line.  Normally, @code{track-eol} is @code{nil}.
        !          1284: 
        !          1285: @section Erasing Text
        !          1286: 
        !          1287: @table @kbd
        !          1288: @item @key{DEL}
        !          1289: Delete the character before the cursor (@code{delete-backward-char}).
        !          1290: @item C-d
        !          1291: Delete the character after the cursor (@code{delete-char}).
        !          1292: @item C-k
        !          1293: Kill to the end of the line (@code{kill-line}).
        !          1294: @end table
        !          1295: 
        !          1296:   You already know about the @key{DEL} key which deletes the character
        !          1297: before the cursor.  Another key, @kbd{Control-d}, deletes the character
        !          1298: after the cursor, causing the rest of the text on the line to shift left.
        !          1299: If @kbd{Control-d} is typed at the end of a line, that line and the next
        !          1300: line are joined together.
        !          1301: 
        !          1302:   To erase a larger amount of text, use the @kbd{Control-k} key, which
        !          1303: kills a line at a time.  If @kbd{Control-k} is done at the beginning or
        !          1304: middle of a line, it kills all the text up to the end of the line.  If
        !          1305: @kbd{Control-k} is done at the end of a line, it joins that line and the
        !          1306: next line.
        !          1307: 
        !          1308:   @xref{Killing}, for more flexible ways of killing text.
        !          1309: 
        !          1310: @section Files
        !          1311: 
        !          1312: @cindex files
        !          1313:   The commands above are sufficient for creating and altering text in an
        !          1314: Emacs buffer; the more advanced Emacs commands just make things easier.
        !          1315: But to keep any text permanently you must put it in a @dfn{file}.  Files
        !          1316: are named units of text which are stored by the operating system for you to
        !          1317: retrieve later by name.  To look at or use the contents of a file in any
        !          1318: way, including editing the file with Emacs, you must specify the file name.
        !          1319: 
        !          1320:   Consider a file named @file{/usr/rms/foo.c}.  To edit this file in Emacs,
        !          1321: type
        !          1322: 
        !          1323: @example
        !          1324: C-x C-f /usr/rms/foo.c @key{RET}
        !          1325: @end example
        !          1326: 
        !          1327: @noindent
        !          1328: Here the file name is given as an @dfn{argument} to the command @kbd{C-x
        !          1329: C-f} (@code{find-file}).  @key{RET} is used to terminate the argument.
        !          1330: Emacs obeys the command by @dfn{visiting} the file: creating a buffer,
        !          1331: copying the contents of the file into the buffer, and then displaying the
        !          1332: buffer for you to edit.  You can make changes in it, and then @dfn{save}
        !          1333: the file by typing @kbd{C-x C-s} (@code{save-buffer}).  This makes the
        !          1334: changes permanent by copying the altered contents of the buffer back into
        !          1335: the file @file{/usr/rms/foo.c}.  Until then, the changes are only inside
        !          1336: your Emacs, and the file @file{foo.c} is not changed.@refill
        !          1337: 
        !          1338:   To create a file, just visit the file with @kbd{C-x C-f} as if it already
        !          1339: existed.  Emacs will make an empty buffer in which you can insert the text
        !          1340: you want to put in the file.  When you save your text with @kbd{C-x C-s},
        !          1341: the file will be created.
        !          1342: 
        !          1343:   Of course, there is a lot more to learn about using files.  @xref{Files}.
        !          1344: 
        !          1345: @section Help
        !          1346: 
        !          1347:   If you forget what a key does, you can find out with the Help character,
        !          1348: which is @kbd{C-h}.  Type @kbd{C-h k} followed by the key you want to know
        !          1349: about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n}
        !          1350: does.  @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its
        !          1351: subcommands (the command @code{describe-key}).  The other subcommands of
        !          1352: @kbd{C-h} provide different kinds of help.  @xref{Help}.@refill
        !          1353: 
        !          1354: @menu
        !          1355: * Blank Lines::        Commands to make or delete blank lines.
        !          1356: * Continuation Lines:: Lines too wide for the screen.
        !          1357: * Position Info::      What page, line, row, or column is point on?
        !          1358: * Arguments::         Numeric arguments for repeating a command.
        !          1359: @end menu
        !          1360: 
        !          1361: @node Blank Lines, Continuation Lines, Basic, Basic
        !          1362: @section Blank Lines
        !          1363: 
        !          1364: @c widecommands
        !          1365: @table @kbd
        !          1366: @item C-o
        !          1367: Insert one or more blank lines after the cursor (@code{open-line}).
        !          1368: @item C-x C-o
        !          1369: Delete all but one of many consecutive blank lines
        !          1370: (@code{delete-blank-lines}).
        !          1371: @end table
        !          1372: 
        !          1373: @kindex C-o
        !          1374: @kindex C-x C-o
        !          1375: @cindex blank lines
        !          1376: @findex open-line
        !          1377: @findex delete-blank-lines
        !          1378:   When you want to insert a new line of text before an existing line, you
        !          1379: can do it by typing the new line of text, followed by @key{RET}.  However,
        !          1380: it may be easier to see what you are doing if you first make a blank line
        !          1381: and then insert the desired text into it.  This is easy to do using the key
        !          1382: @kbd{C-o} (@code{open-line}), which inserts a newline after point but leaves
        !          1383: point in front of the newline.  After @kbd{C-o}, type the text for the new
        !          1384: line.  @kbd{C-o F O O} has the same effect as @kbd{F O O @key{RET}}, except for
        !          1385: the final location of point.
        !          1386: 
        !          1387:   You can make several blank lines by typing @kbd{C-o} several times, or by
        !          1388: giving it an argument to tell it how many blank lines to make.
        !          1389: @xref{Arguments}, for how.
        !          1390: 
        !          1391:   If you have many blank lines in a row and want to get rid of them, use
        !          1392: @kbd{C-x C-o} (@code{delete-blank-lines}).  When point is on a blank line which
        !          1393: is adjacent to at least one other blank line, @kbd{C-x C-o} deletes all but
        !          1394: one of the consecutive blank lines, leaving exactly one.  With point on a
        !          1395: blank line with no other blank line adjacent to it, the sole blank line is
        !          1396: deleted, leaving none.  When point is on a nonblank line, @kbd{C-x C-o}
        !          1397: deletes any blank lines following that nonblank line.
        !          1398: 
        !          1399: @node Continuation Lines, Position Info, Blank Lines, Basic
        !          1400: @section Continuation Lines
        !          1401: 
        !          1402: @cindex continuation line
        !          1403:   If you add too many characters to one line, without breaking it with a
        !          1404: @key{RET}, the line will grow to occupy two (or more) lines on the screen,
        !          1405: with a @samp{\} at the extreme right margin of all but the last of them.
        !          1406: The @samp{\} says that the following screen line is not really a distinct
        !          1407: line in the text, but just the @dfn{continuation} of a line too long to fit
        !          1408: the screen.  Sometimes it is nice to have Emacs insert newlines
        !          1409: automatically when a line gets too long; for this, use Auto Fill mode
        !          1410: (@pxref{Filling}).
        !          1411: 
        !          1412: @vindex truncate-lines
        !          1413: @vindex default-truncate-lines
        !          1414: @cindex truncation
        !          1415:   Continuation can be turned off for a particular buffer by setting the
        !          1416: variable @code{truncate-lines} to non-@code{nil} in that buffer.  Then,
        !          1417: lines are @dfn{truncated}: the text that goes past the right margin does
        !          1418: not appear at all.  @samp{$} is used in the last column instead of @samp{\}
        !          1419: when truncation is in effect.  Truncation instead of continuation also
        !          1420: happens whenever horizontal scrolling is in use, and optionally whenever
        !          1421: side-by-side windows are in use (@pxref{Windows}).  @code{truncate-lines}
        !          1422: is automatically local in all buffers.  When a buffer is created, its value
        !          1423: of @code{truncate-lines} is initialized from the value of @code{default-truncate-lines},
        !          1424: normally @code{nil}.
        !          1425: 
        !          1426: @node Position Info, Arguments, Continuation Lines, Basic
        !          1427: @section Cursor Position Information
        !          1428: 
        !          1429:   If you are accustomed to other display editors, you may be surprised that
        !          1430: Emacs does not always display the page number or line number of point in
        !          1431: the mode line.  This is because the text is stored in a way that makes it
        !          1432: difficult to compute this information.  Displaying them all the time would
        !          1433: be intolerably slow.  They are not needed very often in Emacs anyway,
        !          1434: but there are commands to print them.
        !          1435: 
        !          1436: @table @kbd
        !          1437: @item C-x =
        !          1438: Print character code of character after point, character position of
        !          1439: point, and column of point (@code{what-cursor-position}).
        !          1440: @item M-x what-page
        !          1441: Print page number of point, and line number within page.
        !          1442: @item M-x what-line
        !          1443: Print line number of point in the buffer.
        !          1444: @item M-=
        !          1445: Print number of lines in the current region (@code{count-lines-region}).
        !          1446: @end table
        !          1447: 
        !          1448: @kindex C-x =
        !          1449: @findex what-cursor-position
        !          1450:   The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out
        !          1451: the column that the cursor is in, and other miscellaneous information about
        !          1452: point.  It prints a line in the echo area that looks like this:
        !          1453: 
        !          1454: @example
        !          1455: Char: x (0170)  point=65986 of 563027(12%)  x=44
        !          1456: @end example
        !          1457: 
        !          1458: @noindent
        !          1459: (In fact, this is the output produced when point is before the @samp{x=44}
        !          1460: in the example.)
        !          1461: 
        !          1462:   The two values after @samp{Char:} describe the character following point,
        !          1463: first by showing it and second by giving its octal character code.
        !          1464: 
        !          1465:   @samp{point=} is followed by the position of point expressed as a character
        !          1466: count.  The front of the buffer counts as position 1, one character later
        !          1467: as 2, and so on.  The next, larger number is the total number of characters
        !          1468: in the buffer.  Afterward in parentheses comes the position expressed as a
        !          1469: percentage of the total size.
        !          1470: 
        !          1471:   @samp{x=} is followed by the horizontal position of point, in columns from the
        !          1472: left edge of the window.
        !          1473: 
        !          1474:   If the buffer has been narrowed, making some of the text at the beginning and
        !          1475: the end temporarily invisible, @kbd{C-x =} prints additional text describing the
        !          1476: current visible range.  For example, it might say
        !          1477: 
        !          1478: @smallexample
        !          1479: Char: x (0170)  point=65986 of 563025(12%) <65102 - 68533>  x=44
        !          1480: @end smallexample
        !          1481: 
        !          1482: @noindent
        !          1483: where the two extra numbers give the smallest and largest character position
        !          1484: that point is allowed to assume.  The characters between those two positions
        !          1485: are the visible ones.  @xref{Narrowing}.
        !          1486: 
        !          1487:   If point is at the end of the buffer (or the end of the visible part),
        !          1488: @kbd{C-x =} omits any description of the character after point.
        !          1489: The output looks like
        !          1490: 
        !          1491: @smallexample
        !          1492: point=563026 of 563025(100%)  x=0
        !          1493: @end smallexample
        !          1494: 
        !          1495: @noindent
        !          1496: Usually @samp{x=0} at the end, because the text usually ends with a newline.
        !          1497: 
        !          1498: @findex what-page
        !          1499: @findex what-line
        !          1500:   There are two commands for printing line numbers.  @kbd{M-x what-line}
        !          1501: counts lines from the beginning of the file and prints the line number
        !          1502: point is on.  The first line of the file is line number 1.  By contrast,
        !          1503: @kbd{M-x what-page} counts pages from the beginning of the file, and
        !          1504: counts lines within the page, printing both of them.  @xref{Pages}.
        !          1505: 
        !          1506: @kindex M-=
        !          1507: @findex count-lines-region
        !          1508:   While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}),
        !          1509: which prints the number of lines in the region (@pxref{Mark}).
        !          1510: @xref{Pages}, for the command @kbd{C-x l} which counts the lines in the
        !          1511: current page.
        !          1512: 
        !          1513: @node Arguments,, Position Info, Basic
        !          1514: @section Numeric Arguments
        !          1515: @cindex numeric arguments
        !          1516: 
        !          1517:   Any Emacs command can be given a @dfn{numeric argument}.  Some commands
        !          1518: interpret the argument as a repetition count.  For example, giving an
        !          1519: argument of ten to the key @kbd{C-f} (the command @code{forward-char}, move
        !          1520: forward one character) moves forward ten characters.  With these commands,
        !          1521: no argument is equivalent to an argument of one.  Negative arguments are
        !          1522: allowed.  Often they tell a command to move or act backwards.
        !          1523: 
        !          1524: @kindex M-1
        !          1525: @kindex M--
        !          1526: @findex digit-argument
        !          1527: @findex negative-argument
        !          1528:   If your terminal keyboard has a @key{META} key, the easiest way to
        !          1529: specify a numeric argument is to type digits and/or a minus sign while
        !          1530: holding down the the @key{META} key.  For example,
        !          1531: @example
        !          1532: M-5 C-n
        !          1533: @end example
        !          1534: @noindent
        !          1535: would move down five lines.  The characters @kbd{Meta-1}, @kbd{Meta-2},
        !          1536: etc., and @kbd{Meta--}, do this because they are keys bound to commands
        !          1537: (@code{digit-argument} and @code{negative-argument}) that are defined to
        !          1538: contribute to an argument for the next command.
        !          1539: 
        !          1540: @kindex C-u
        !          1541: @findex universal-argument
        !          1542:   Another way of specifying an argument is to use the @kbd{C-u}
        !          1543: (@code{universal-argument}) command followed by the digits of the argument.
        !          1544: With @kbd{C-u}, you can type the argument digits without holding
        !          1545: down shift keys.  To type a negative argument, start with a minus sign.
        !          1546: Just a minus sign normally means -1.  @kbd{C-u} works on all terminals.
        !          1547: 
        !          1548:   @kbd{C-u} followed by a character which is neither a digit nor a minus
        !          1549: sign has the special meaning of ``multiply by four''.  It multiplies the
        !          1550: argument for the next command by four.  @kbd{C-u} twice multiplies it by
        !          1551: sixteen.  Thus, @kbd{C-u C-u C-f} moves forward sixteen characters.  This
        !          1552: is a good way to move forward ``fast'', since it moves about 1/5 of a line
        !          1553: in the usual size screen.  Other useful combinations are @kbd{C-u C-n},
        !          1554: @kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u
        !          1555: C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four
        !          1556: lines).@refill
        !          1557: 
        !          1558:   Some commands care only about whether there is an argument, and not about
        !          1559: its value.  For example, the command @kbd{M-q} (@code{fill-paragraph}) with
        !          1560: no argument fills text; with an argument, it justifies the text as well.
        !          1561: (@xref{Filling}, for more information on @kbd{M-q}.)  Just @kbd{C-u} is a
        !          1562: handy way of providing an argument for such commands.
        !          1563: 
        !          1564:   Some commands use the value of the argument as a repeat count, but do
        !          1565: something peculiar when there is no argument.  For example, the command
        !          1566: @kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines,
        !          1567: including their terminating newlines.  But @kbd{C-k} with no argument is
        !          1568: special: it kills the text up to the next newline, or, if point is right at
        !          1569: the end of the line, it kills the newline itself.  Thus, two @kbd{C-k}
        !          1570: commands with no arguments can kill a nonblank line, just like @kbd{C-k}
        !          1571: with an argument of one.  (@xref{Killing}, for more information on
        !          1572: @kbd{C-k}.)@refill
        !          1573: 
        !          1574:   A few commands treat a plain @kbd{C-u} differently from an ordinary
        !          1575: argument.  A few others may treat an argument of just a minus sign
        !          1576: differently from an argument of -1.  These unusual cases will be described
        !          1577: when they come up; they are always for reasons of convenience of use of the
        !          1578: individual command.
        !          1579: 
        !          1580: @c section Autoarg Mode
        !          1581: @ignore
        !          1582: @cindex autoarg mode
        !          1583:   Users of ASCII keyboards may prefer to use Autoarg mode.  Autoarg mode
        !          1584: means that you don't need to type C-U to specify a numeric argument.
        !          1585: Instead, you type just the digits.  Digits followed by an ordinary
        !          1586: inserting character are themselves inserted, but digits followed by an
        !          1587: Escape or Control character serve as an argument to it and are not
        !          1588: inserted.  A minus sign can also be part of an argument, but only at the
        !          1589: beginning.  If you type a minus sign following some digits, both the digits
        !          1590: and the minus sign are inserted.
        !          1591: 
        !          1592:   To use Autoarg mode, set the variable Autoarg Mode nonzero.
        !          1593: @xref{Variables}.
        !          1594: 
        !          1595:   Autoargument digits echo at the bottom of the screen; the first nondigit
        !          1596: causes them to be inserted or uses them as an argument.  To insert some
        !          1597: digits and nothing else, you must follow them with a Space and then rub it
        !          1598: out.  C-G cancels the digits, while Delete inserts them all and then rubs
        !          1599: out the last.
        !          1600: @end ignore
        !          1601: 
        !          1602: @node Undo, Minibuffer, Basic, Top
        !          1603: @chapter Undoing Changes
        !          1604: @cindex undo
        !          1605: 
        !          1606:   Emacs allows all changes made in the text of a buffer to be undone,
        !          1607: up to a certain amount of change (8000 characters).  Each buffer records
        !          1608: changes individually, and the undo command always applies to the
        !          1609: current buffer.  Usually each editing command makes a separate entry
        !          1610: in the undo records, but some commands such as @code{query-replace}
        !          1611: make many entries, and very simple commands such as self-inserting
        !          1612: characters are often grouped to make undoing less tedious.
        !          1613: 
        !          1614: @table @kbd
        !          1615: @item C-x u
        !          1616: Undo one batch of changes (usually, one command worth) (@code{undo}).
        !          1617: @item C-_
        !          1618: The same.
        !          1619: @end table
        !          1620: 
        !          1621: @kindex C-x u
        !          1622: @kindex C-_
        !          1623: @findex undo
        !          1624:   The command @kbd{C-x u} or @kbd{C-_} is how you undo.  The first
        !          1625: time you give this command, it undoes the last change.  Point moves to
        !          1626: the beginning of the text affected by the undo, so you can see what
        !          1627: was undone.@refill
        !          1628: 
        !          1629:   Consecutive repetitions of the @kbd{C-_} or @kbd{C-x u} commands undo
        !          1630: earlier and earlier changes, back to the limit of what has been recorded.
        !          1631: If all recorded changes have already been undone, the undo command gets an
        !          1632: error.
        !          1633: 
        !          1634:   Any command other than an undo command breaks the sequence of undo
        !          1635: commands.  Starting at this moment, the previous undo commands are
        !          1636: considered ordinary changes that can themselves be undone.  Thus, you can
        !          1637: redo changes you have undone by typing @kbd{C-@key{SPC}}, @kbd{C-f} or any
        !          1638: other command that will have no important effect, and then using more undo
        !          1639: commands.
        !          1640: 
        !          1641:   If you notice that a buffer has been modified accidentally, the easiest
        !          1642: way to recover is to type @kbd{C-_} repeatedly until the stars disappear
        !          1643: from the front of the mode line.  At this time, all the modifications you
        !          1644: made have been cancelled.  If you do not remember whether you changed the
        !          1645: buffer deliberately, type @kbd{C-_} once, and when you see the last change
        !          1646: you made undone, you will remember why you made it.  If it was an accident,
        !          1647: leave it undone.  If it was deliberate, redo the change as described in the
        !          1648: preceding paragraph.
        !          1649: 
        !          1650:   Not all buffers record undo information.  Buffers whose names start with
        !          1651: spaces don't; these buffers are used internally by Emacs and its extensions
        !          1652: to hold text that users don't normally look at or edit.  Also, minibuffers,
        !          1653: help buffers and documentation buffers don't record undo information.
        !          1654: 
        !          1655:   At most 8000 or so characters of deleted or modified text can be
        !          1656: remembered in any one buffer for reinsertion by the undo command.  Also,
        !          1657: there is a limit on the number of individual insert, delete or change
        !          1658: actions that can be remembered.
        !          1659: 
        !          1660:   The reason the @code{undo} command has two keys, @kbd{C-x u} and @kbd{C-_}, set
        !          1661: up to run it is that it is worthy of a single-character key, but the way to
        !          1662: type @kbd{C-_} on some keyboards is not obvious.  @kbd{C-x u} is an
        !          1663: alternative that requires no special knowledge of the terminal.
        !          1664: 
        !          1665: @node Minibuffer, M-x, Undo, Top
        !          1666: @chapter The Minibuffer
        !          1667: @cindex minibuffer
        !          1668: 
        !          1669:   The @dfn{minibuffer} is the facility used by Emacs commands to read
        !          1670: arguments more complicated than a single number.  Minibuffer arguments can
        !          1671: be file names, buffer names, Lisp function names, Emacs command names, Lisp
        !          1672: expressions, and many other things, depending on the command reading the
        !          1673: argument.  The usual Emacs editing commands can be used to edit in the
        !          1674: minibuffer also.
        !          1675: 
        !          1676: @cindex prompt
        !          1677:   When the minibuffer is in use, it appears in the echo area, and the
        !          1678: terminal's cursor moves there.  The beginning of the minibuffer line
        !          1679: displays a @dfn{prompt} which says what kind of input you should supply and
        !          1680: how it will be used.  Often this prompt is derived from the name of the
        !          1681: command that the argument is for.  The prompt normally ends with a colon.
        !          1682: 
        !          1683: @cindex default argument
        !          1684:   Sometimes a @dfn{default argument} appears in parentheses after the
        !          1685: colon; it too is part of the prompt.  The default will be used as the
        !          1686: argument value if you enter an empty argument (e.g., just type @key{RET}).
        !          1687: For example, commands that read buffer names always show a default, which
        !          1688: is the name of the buffer that will be used if you type just @key{RET}.
        !          1689: 
        !          1690: @kindex C-g
        !          1691:   The simplest way to give a minibuffer argument is to type the text you
        !          1692: want, terminated by @key{RET} which exits the minibuffer.  You can get out
        !          1693: of the minibuffer, canceling the command that it was for, by typing
        !          1694: @kbd{C-g}.
        !          1695: 
        !          1696:   Since the minibuffer uses the screen space of the echo area, it can
        !          1697: conflict with other ways Emacs customarily uses the echo area.  Here is how
        !          1698: Emacs handles such conflicts:
        !          1699: 
        !          1700: @itemize @bullet
        !          1701: @item
        !          1702: If a command gets an error while you are in the minibuffer, this does
        !          1703: not cancel the minibuffer.  However, the echo area is needed for the
        !          1704: error message and therefore the minibuffer itself is hidden for a
        !          1705: while.  It comes back after a few seconds.
        !          1706: 
        !          1707: @item
        !          1708: If in the minibuffer you use a command whose purpose is to print a
        !          1709: message in the echo area, such as @kbd{C-x =}, the message is printed
        !          1710: normally, and the minibuffer is hidden for a while.  It comes back
        !          1711: after a few seconds.
        !          1712: 
        !          1713: @item
        !          1714: Echoing of keystrokes does not take place while the minibuffer is in
        !          1715: use.
        !          1716: @end itemize
        !          1717: 
        !          1718: @menu
        !          1719: * File: Minibuffer File.  Entering file names with the minibuffer.
        !          1720: * Edit: Minibuffer Edit.  How to edit in the minibuffer.
        !          1721: * Completion::           An abbreviation facility for minibuffer input.
        !          1722: * Repetition::           Re-executing commands that used the minibuffer.
        !          1723: @end menu
        !          1724: 
        !          1725: @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
        !          1726: @section Minibuffers for File Names
        !          1727: 
        !          1728:   Sometimes the minibuffer starts out with text in it.  For example, when
        !          1729: you are supposed to give a file name, the minibuffer starts out containing
        !          1730: the @dfn{default directory}, which ends with a slash.  This is to inform
        !          1731: you which directory the file will be found in if you do not specify a
        !          1732: directory.  For example, the minibuffer might start out with
        !          1733: 
        !          1734: @example
        !          1735: Find File: /u2/emacs/src/
        !          1736: @end example
        !          1737: 
        !          1738: @noindent
        !          1739: where @samp{Find File:@: } is the prompt.  Typing @kbd{buffer.c} specifies
        !          1740: the file @file{/u2/emacs/src/buffer.c}.  To find files in nearby
        !          1741: directories, use @kbd{..}; thus, if you type @kbd{../lisp/simple.el}, the
        !          1742: file that you visit will be the one named @file{/u2/emacs/lisp/simple.el}.
        !          1743: Alternatively, you can kill with @kbd{M-@key{DEL}} the directory names you
        !          1744: don't want (@pxref{Words}).@refill
        !          1745: 
        !          1746:   You can also type an absolute file name, one starting with a slash or a
        !          1747: tilde, ignoring the default directory.  For example, to find the file
        !          1748: @file{/etc/termcap}, just type the name, giving
        !          1749: 
        !          1750: @example
        !          1751: Find File: /u2/emacs/src//etc/termcap
        !          1752: @end example
        !          1753: 
        !          1754: @noindent
        !          1755: Two slashes in a row are not normally meaningful in Unix file names, but
        !          1756: they are allowed in GNU Emacs.  They mean, ``ignore everything before the
        !          1757: second slash in the pair.''  Thus, @samp{/u2/emacs/src/} is ignored, and
        !          1758: you get the file @file{/etc/termcap}.
        !          1759: 
        !          1760: @vindex insert-default-directory
        !          1761:   If you set @code{insert-default-directory} to @code{nil}, the default directory
        !          1762: is not inserted in the minibuffer.  This way, the minibuffer starts out
        !          1763: empty.  But the name you type, if relative, is still interpreted with
        !          1764: respect to the same default directory.
        !          1765: 
        !          1766: @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
        !          1767: @section Editing in the Minibuffer
        !          1768: 
        !          1769:   The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
        !          1770: Emacs commands are available for editing the text of an argument you are
        !          1771: entering.
        !          1772: 
        !          1773:   Since @key{RET} in the minibuffer is defined to exit the minibuffer,
        !          1774: inserting a newline into the minibuffer must be done with @kbd{C-o} or with
        !          1775: @kbd{C-q @key{LFD}}.  (Recall that a newline is really the @key{LFD}
        !          1776: character.)
        !          1777: 
        !          1778:   The minibuffer has its own window which always has space on the screen
        !          1779: but acts as if it were not there when the minibuffer is not in use.  When
        !          1780: the minibuffer is in use, its window is just like the others; you can
        !          1781: switch to another window with @kbd{C-x o}, edit text in other windows and
        !          1782: perhaps even visit more files, before returning to the minibuffer to submit
        !          1783: the argument.  You can kill text in another window, return to the
        !          1784: minibuffer window, and then yank the text to use it in the argument.
        !          1785: @xref{Windows}.
        !          1786: 
        !          1787:   There are some restrictions on the use of the minibuffer window, however.
        !          1788: You cannot switch buffers in it---the minibuffer and its window are
        !          1789: permanently attached.  Also, you cannot split the minibuffer window.
        !          1790: 
        !          1791:   Recursive use of the minibuffer is supported by Emacs.  However, it is
        !          1792: easy to do this by accident (because of autorepeating keyboards, for
        !          1793: example) and get confused.  Therefore, most Emacs commands that use the
        !          1794: minibuffer refuse to operate if the minibuffer window is selected.  If the
        !          1795: minibuffer is active but you have switched to a different window, recursive
        !          1796: use of the minibuffer is allowed---if you know enough to try to do this,
        !          1797: you probably will not get confused.
        !          1798: 
        !          1799: @vindex enable-recursive-minibuffers
        !          1800:   If you set the variable @code{enable-recursive-minibuffers} to be
        !          1801: non-@code{nil}, recursive use of the minibuffer is always allowed.
        !          1802: 
        !          1803: @node Completion, Repetition, Minibuffer Edit, Minibuffer
        !          1804: @section Completion
        !          1805: @cindex completion
        !          1806: 
        !          1807:   When appropriate, the minibuffer provides a @dfn{completion} facility.
        !          1808: This means that you type enough of the argument to determine the rest,
        !          1809: based on Emacs's knowledge of which arguments make sense, and Emacs visibly
        !          1810: fills in the rest, or as much as can be determined from the part you have
        !          1811: typed.
        !          1812: 
        !          1813:   When completion is available, certain keys---@key{TAB}, @key{RET}, and @key{SPC}---are
        !          1814: redefined to complete an abbreviation present in the minibuffer into a
        !          1815: longer string that it stands for, by matching it against a set of
        !          1816: @dfn{completion alternatives} provided by the command reading the argument.
        !          1817: @kbd{?} is defined to display a list of possible completions of what you
        !          1818: have inserted.
        !          1819: 
        !          1820:   For example, when the minibuffer is being used by @kbd{Meta-x} to read
        !          1821: the name of a command, it is given a list of all available Emacs command
        !          1822: names to complete against.  The completion keys match the text in the
        !          1823: minibuffer against all the command names, find any additional characters of
        !          1824: the name that are implied by the ones already present in the minibuffer,
        !          1825: and add those characters to the ones you have given.
        !          1826: 
        !          1827: @kindex TAB
        !          1828: @findex minibuffer-complete
        !          1829:   A concrete example may help here.  If you type @kbd{Meta-x au @key{TAB}}, the @key{TAB}
        !          1830: looks for alternatives (in this case, command names) that start with
        !          1831: @samp{au}.  In this case, there are only two: @code{auto-fill-mode} and
        !          1832: @code{auto-save-mode}.  These are the same as far as @code{auto-}, so the
        !          1833: @samp{au} in the minibuffer changes to @samp{auto-}.
        !          1834: 
        !          1835:   If you go on to type @kbd{f @key{TAB}}, this second @key{TAB} sees @samp{auto-f}.
        !          1836: The only command name starting this way is @code{auto-fill-mode}, so that
        !          1837: is the completion.  You have now have @samp{auto-fill-mode} in the
        !          1838: minibuffer after typing just @kbd{au @key{TAB} f @key{TAB}}.  Note that
        !          1839: @key{TAB} has this effect because in the minibuffer it is bound to the
        !          1840: function @code{minibuffer-complete} when completion is supposed to be done.
        !          1841: 
        !          1842:   Case is normally significant in completion, because it is significant in
        !          1843: most of the names that you can complete (buffer names, file names and
        !          1844: command names).  Thus, @samp{fo} will not complete to @samp{Foo}.  When you
        !          1845: are completing a name in which case does not matter, the program can request
        !          1846: that case be ignored for completion as well.
        !          1847: 
        !          1848:   Here is a list of all the completion commands, defined in the minibuffer
        !          1849: when completion is available.
        !          1850: 
        !          1851: @table @kbd
        !          1852: @item @key{TAB}
        !          1853: Complete the text in the minibuffer as much as possible @*
        !          1854: (@code{minibuffer-complete}).
        !          1855: @item @key{SPC}
        !          1856: Complete the text in the minibuffer but don't add or fill out more
        !          1857: than one word (@code{minibuffer-complete-word}).
        !          1858: @item @key{RET}
        !          1859: Submit the text in the minibuffer as the argument, possibly completing
        !          1860: first as described below (@code{minibuffer-complete-and-exit}).
        !          1861: @item ?
        !          1862: Print a list of all possible completions of the text in the minibuffer
        !          1863: (@code{minibuffer-list-completions}).
        !          1864: @end table
        !          1865: 
        !          1866: @kindex SPC
        !          1867: @findex minibuffer-complete-word
        !          1868:   @key{SPC} completes much like @key{TAB}, but never adds goes beyond the
        !          1869: next hyphen.  If you have @samp{auto-f} in the minibuffer and type
        !          1870: @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but it
        !          1871: stops completing after @samp{fill-}.  This gives @samp{auto-fill-}.
        !          1872: Another @key{SPC} at this point completes all the way to
        !          1873: @samp{auto-fill-mode}.  @key{SPC} in the minibuffer runs the function
        !          1874: @code{minibuffer-complete-word} when completion is available.
        !          1875: 
        !          1876:   There are three different ways that @key{RET} can work in completing
        !          1877: minibuffers, depending on how the argument will be used.
        !          1878: 
        !          1879: @itemize @bullet
        !          1880: @item
        !          1881: @dfn{Strict} completion is used when it is meaningless to give any
        !          1882: argument except one of the known alternatives.  For example, when
        !          1883: @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
        !          1884: give anything but the name of an existing buffer.  In strict
        !          1885: completion, @key{RET} refuses to exit if the text in the minibuffer
        !          1886: does not complete to an exact match.
        !          1887: 
        !          1888: @item
        !          1889: @dfn{Cautious} completion is similar to strict completion, except that
        !          1890: @key{RET} exits only if the text was an exact match already, not
        !          1891: needing completion.  If the text is not an exact match, @key{RET} does
        !          1892: not exit, but it does complete the text.  If it completes to an exact
        !          1893: match, a second @key{RET} will exit.
        !          1894: 
        !          1895: Cautious completion is used for reading file names for files that must
        !          1896: already exist.
        !          1897: 
        !          1898: @item
        !          1899: @dfn{Permissive} completion is used when any string whatever is
        !          1900: meaningful, and the list of completion alternatives is just a guide.
        !          1901: For example, when @kbd{C-x C-f} reads the name of a file to visit, any
        !          1902: file name is allowed, in case you want to create a file.  In
        !          1903: permissive completion, @key{RET} takes the text in the minibuffer
        !          1904: exactly as given, without completing it.
        !          1905: @end itemize
        !          1906: 
        !          1907: @vindex completion-ignored-extensions
        !          1908:   When completion is done on file names, certain file names are usually
        !          1909: ignored.  The variable @code{completion-ignored-extensions} contains a list
        !          1910: of strings; a file whose name ends in any of those strings is ignored as a
        !          1911: possible completion.  The standard value of this variable is @code{(".o"
        !          1912: ".elc" "~")}, which is designed to allow @samp{foo} to complete to
        !          1913: @samp{foo.c} even though @samp{foo.o} exists as well.  If the only possible
        !          1914: completions are files that end in ``ignored'' strings, then they are not
        !          1915: ignored.
        !          1916: 
        !          1917: @node Repetition,, Completion, Minibuffer
        !          1918: @section Repeating Minibuffer Commands
        !          1919: 
        !          1920:   Every command that uses the minibuffer at least once is recorded on a
        !          1921: special history list, together with the values of the minibuffer arguments,
        !          1922: so that you can repeat the command easily.  In particular, every
        !          1923: use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to
        !          1924: read the command name.
        !          1925: 
        !          1926: @c widecommands
        !          1927: @table @kbd
        !          1928: @item C-x @key{ESC}
        !          1929: Re-execute a recent minibuffer command @*(@code{repeat-complex-command}).
        !          1930: @end table
        !          1931: 
        !          1932: @kindex C-x ESC
        !          1933: @findex repeat-complex-command
        !          1934:   @kbd{C-x @key{ESC}} is used to re-execute a recent minibuffer-using
        !          1935: command.  With no argument, it repeats the last such command.  A numeric
        !          1936: argument specifies which command to repeat; one means the last one, and
        !          1937: larger numbers specify earlier ones.
        !          1938: 
        !          1939:   @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp
        !          1940: expression and then entering a minibuffer initialized with the text for
        !          1941: that expression.  If you type just @key{RET}, the command is repeated as
        !          1942: before.  You can also change the command by editing the Lisp expression.
        !          1943: Whatever expression you finally submit is what will be executed.  The
        !          1944: repeated command does not go on the command history itself; @kbd{C-x
        !          1945: @key{ESC}} does not alter the command history.
        !          1946: 
        !          1947: @kindex M-n
        !          1948: @kindex M-p
        !          1949: @findex next-complex-command
        !          1950: @findex previous-complex-command
        !          1951:   Once inside the minibuffer for @kbd{C-x @key{ESC}}, if the command shown
        !          1952: to you is not the one you want to repeat, you can move around the list of
        !          1953: previous commands using @kbd{M-n} and @kbd{M-p}.  @kbd{M-p} replaces the
        !          1954: contents of the minibuffer with the next earlier recorded command, and
        !          1955: @kbd{M-n} replaces them with the next later command.  After finding the
        !          1956: desired previous command, you can edit its expression as usual and then
        !          1957: resubmit it by typing @key{RET} as usual.  Any editing you have done on the
        !          1958: command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
        !          1959: 
        !          1960:   @kbd{M-p} is more useful than @kbd{M-n}, since more often you will
        !          1961: initially request to repeat the most recent command and then decide to
        !          1962: repeat an older one instead.  These keys are specially defined within
        !          1963: @kbd{C-x @key{ESC}} to run the commands @code{next-complex-command} and
        !          1964: @code{previous-complex-command}.
        !          1965: 
        !          1966: @vindex command-history
        !          1967:   The list of previous minibuffer-using commands is stored as a Lisp list
        !          1968: in the variable @code{command-history}.  Each element is a Lisp expression
        !          1969: which describes one command and its arguments.  The command can be
        !          1970: reexecuted by feeding the corresponding @code{command-history} element to
        !          1971: @code{eval}.
        !          1972: 
        !          1973: @node M-x, Help, Minibuffer, Top
        !          1974: @chapter Running Commands by Name
        !          1975: 
        !          1976:   The Emacs commands that are used often or that must be quick to type are
        !          1977: bound to keys---short sequences of characters---for convenient use.  Other
        !          1978: Emacs commands that do not need to be brief are not bound to keys; to run
        !          1979: them, you must refer to them by name.
        !          1980: 
        !          1981:   A command name is, by convention, made up of one or more words, separated
        !          1982: by hyphens; for example, @code{auto-fill-mode} or @code{manual-entry}.  The
        !          1983: use of English words makes the command name easier to remember than a key
        !          1984: made up of obscure characters, even though it is more characters to type.
        !          1985: Any command can be run by name, even if it is also runnable by keys.
        !          1986: 
        !          1987: @kindex M-x
        !          1988: @findex execute-extended-command
        !          1989: @cindex minibuffer
        !          1990:   The way to run a command by name is to start with @kbd{M-x}, type the
        !          1991: command name, and finish it with @key{RET}.  Actually, @kbd{M-x} (the command
        !          1992: @code{execute-extended-command}) is using the minibuffer to read the
        !          1993: command name.
        !          1994: 
        !          1995:   Emacs uses the minibuffer for reading input for many different purposes;
        !          1996: on this occasion, the string @samp{M-x} is displayed at the beginning of
        !          1997: the minibuffer as a @dfn{prompt} to remind you that your input should be
        !          1998: the name of a command to be run.  @xref{Minibuffer}, for full information
        !          1999: the features of the minibuffer.
        !          2000: 
        !          2001:   You can use completion to enter the command name.  For example, the
        !          2002: command @code{forward-char} can be invoked by name by typing
        !          2003: 
        !          2004: @example
        !          2005: M-x forward-char @key{RET}
        !          2006: 
        !          2007: @exdent or
        !          2008: 
        !          2009: M-x fo @key{TAB} c @key{RET}
        !          2010: @end example
        !          2011: 
        !          2012: @noindent
        !          2013: Note that @code{forward-char} is the same command that you invoke with
        !          2014: the key @kbd{C-f}.  Any command (interactively callable function) defined
        !          2015: in Emacs can be called by its name using @kbd{M-x} whether or not any
        !          2016: keys are bound to it.
        !          2017: 
        !          2018:   If you type @kbd{C-g} while the command name is being read, you cancel
        !          2019: the @kbd{M-x} command and get out of the minibuffer, ending up at top level.
        !          2020: 
        !          2021:   To pass a numeric argument to the command you are invoking with
        !          2022: @kbd{M-x}, specify the numeric argument before the @kbd{M-x}.  @kbd{M-x}
        !          2023: passes the argument along to the function which it calls.  The argument
        !          2024: value appears in the prompt while the command name is being read.
        !          2025: 
        !          2026:   Normally, when describing a command that is run by name, we omit the
        !          2027: @key{RET} that is needed to terminate the name.  Thus we might speak of
        !          2028: @kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode @key{RET}}.
        !          2029: We mention the @key{RET} only when there is a need to emphasize its
        !          2030: presence, such as when describing a sequence of input that contains a
        !          2031: command name and arguments that follow it.
        !          2032: 
        !          2033: @iftex
        !          2034:   In this manual, the convention for font usage is that Lisp objects,
        !          2035: including command names (which are Lisp symbols), appear in @code{this
        !          2036: font}, but keyboard input appears in @kbd{this font}.  This brings up
        !          2037: a problem with names of commands that are normally run by name: is the
        !          2038: name a piece of Lisp code, or is it a sequence of characters to type?
        !          2039: Unfortunately, it is both, but only one of the two fonts can be used.
        !          2040: I have chosen to use the Lisp object font when discussing the command,
        !          2041: as in @code{auto-fill-mode}, but to use the keyboard input font for
        !          2042: sequences of input, as in @kbd{M-x auto-fill-mode}.
        !          2043: @end iftex
        !          2044: 
        !          2045: @node Help, Mark, M-x, Top
        !          2046: @chapter Help
        !          2047: @kindex Help
        !          2048: @cindex help
        !          2049: @cindex self-documentation
        !          2050: 
        !          2051:   Emacs provides extensive help features which revolve around a single
        !          2052: character, @kbd{C-h}.  @kbd{C-h} is a prefix key that is used only for
        !          2053: documentation-printing commands.  The characters that you can type after
        !          2054: @kbd{C-h} are called @dfn{help options}.  One help option is @kbd{C-h};
        !          2055: that is how you ask for help about using @kbd{C-h}.
        !          2056: 
        !          2057:   @kbd{C-h C-h} prints a list of the possible help options, and then asks
        !          2058: you to go ahead and type the option.  It prompts with a string
        !          2059: 
        !          2060: @smallexample
        !          2061: A, C, F, I, K, L, M, N, S, T, V, W, C-c, C-d, C-w or C-h for more help: 
        !          2062: @end smallexample
        !          2063: 
        !          2064: @noindent
        !          2065: and you should type one of those characters.  Typing a third @kbd{C-h}
        !          2066: displays a description of what the options mean; it still waits for you to
        !          2067: type an option.  To cancel, type @kbd{C-g}.
        !          2068: 
        !          2069:   Here is a summary of the defined help commands.
        !          2070: 
        !          2071: @table @kbd
        !          2072: @item C-h a
        !          2073: Display list of commands whose names contain a specified string
        !          2074: (@code{command-apropos}).
        !          2075: @item C-h b
        !          2076: Display a table of all key bindings in effect now; local bindings of
        !          2077: the current major mode first, followed by all global bindings
        !          2078: (@code{describe-bindings}).
        !          2079: @item C-h c @var{key}
        !          2080: Print the name of the command that @var{key} runs (@code{describe-key-briefly}).
        !          2081: @kbd{c} is for `character'.
        !          2082: @item C-h f @var{function} @key{RET}
        !          2083: Display documentation on the Lisp function named @var{function}
        !          2084: (@code{describe-function}).  Note that commands are Lisp functions, so
        !          2085: a command name may be used.
        !          2086: @item C-h k @var{key}
        !          2087: Display name and documentation of the command @var{key} runs (@code{describe-key}).
        !          2088: @item C-h i
        !          2089: Run Info, the program for browsing documentation files (@code{info}).
        !          2090: @item C-h l
        !          2091: Display a description of the last 100 characters you typed
        !          2092: (@code{view-lossage}).
        !          2093: @item C-h m
        !          2094: Display documentation of the current major mode (@code{describe-mode}).
        !          2095: @item C-h n
        !          2096: Display documentation of Emacs changes, most recent first
        !          2097: (@code{view-emacs-news}).
        !          2098: @item C-h s
        !          2099: Display current contents of the syntax table, plus an explanation of
        !          2100: what they mean (@code{describe-syntax}).
        !          2101: @item C-h t
        !          2102: Display the Emacs tutorial (@code{help-with-tutorial}).
        !          2103: @item C-h v @var{var} @key{RET}
        !          2104: Display the documentation of the Lisp variable @var{var}
        !          2105: (@code{describe-variable}).
        !          2106: @item C-h w @var{command} @key{RET}
        !          2107: Print which keys run the command named @var{command} (@code{where-is}).
        !          2108: @end table
        !          2109: 
        !          2110: @section Documentation for a Key
        !          2111: 
        !          2112: @kindex C-h c
        !          2113: @findex describe-key-briefly
        !          2114:   The most basic @kbd{C-h} options are @kbd{C-h c}
        !          2115: (@code{describe-key-briefly}) and @kbd{C-h k} (@code{describe-key}).
        !          2116: @kbd{C-h c @var{key}} prints in the echo area the name of the command that
        !          2117: @var{key} is bound to.  For example, @kbd{C-h c C-f} prints
        !          2118: @samp{forward-char}.  Since command names are chosen to describe what the
        !          2119: command does, this is a good way to get a very brief description of what
        !          2120: @var{key} does.@refill
        !          2121: 
        !          2122: @kindex C-h k
        !          2123: @findex describe-key
        !          2124:   @kbd{C-h k @var{key}} is similar but gives more information.  It displays
        !          2125: the documentation string of the command @var{key} is bound to as well as
        !          2126: its name.  This is too big for the echo area, so a window is used for the
        !          2127: display.
        !          2128: 
        !          2129: @section Help by Command or Variable Name
        !          2130: 
        !          2131: @kindex C-h f
        !          2132: @findex describe-function
        !          2133:   @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
        !          2134: using the minibuffer, then displays that function's documentation string
        !          2135: in a window.  Since commands are Lisp functions, you can use this to get
        !          2136: the documentation of a command that is known by name.  For example,
        !          2137: 
        !          2138: @example
        !          2139: C-h f auto-fill-mode @key{RET}
        !          2140: @end example
        !          2141: 
        !          2142: @noindent
        !          2143: displays the documentation of @code{auto-fill-mode}.  This is the only
        !          2144: way to see the documentation of a command that is not bound to any key
        !          2145: (one which you would normally call using @kbd{M-x}).
        !          2146: 
        !          2147:   @kbd{C-h f} is also useful for Lisp functions that you are planning to
        !          2148: use in a Lisp program.  For example, if you have just written the code
        !          2149: @code{(make-vector len)} and want to be sure that you are using
        !          2150: @code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}.  Because
        !          2151: @kbd{C-h f} allows all function names, not just command names, you may find
        !          2152: that some of your favorite abbreviations that work in @kbd{M-x} don't work
        !          2153: in @kbd{C-h f}.  An abbreviation may be unique among command names yet fail
        !          2154: to be unique when other function names are allowed.
        !          2155: 
        !          2156:   The function name for @kbd{C-h f} to describe has a default which is
        !          2157: used if you type @key{RET} leaving the minibuffer empty.  The default is
        !          2158: the function called by the innermost Lisp expression in the buffer around
        !          2159: point, @i{provided} that is a valid, defined Lisp function name.  For
        !          2160: example, if point is located following the text @samp{(make-vector (car
        !          2161: x)}, the innermost list containing point is the one that starts with
        !          2162: @samp{(make-vector}, so the default is to describe the function
        !          2163: @code{make-vector}.
        !          2164: 
        !          2165:   @kbd{C-h f} is often useful just to verify that you have the right
        !          2166: spelling for the function name.  If @kbd{C-h f} mentions a default in the
        !          2167: prompt, you have typed the name of a defined Lisp function.  If that tells
        !          2168: you what you want to know, just type @kbd{C-g} to cancel the @kbd{C-h f}
        !          2169: command and go on editing.
        !          2170: 
        !          2171: @kindex C-h w
        !          2172: @findex where-is
        !          2173:   @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
        !          2174: @var{command}.  It prints a list of the keys in the echo area.
        !          2175: Alternatively, it says that the command is not on any keys, which implies
        !          2176: that you must use @kbd{M-x} to call it.@refill
        !          2177: 
        !          2178: @kindex C-h v
        !          2179: @findex describe-variable
        !          2180:   @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
        !          2181: Lisp variables instead of Lisp functions.  Its default is the Lisp symbol
        !          2182: around or before point, but only if that is the name of a known Lisp
        !          2183: variable.  @xref{Variables}.@refill
        !          2184: 
        !          2185: @section Apropos
        !          2186: 
        !          2187: @kindex C-h a
        !          2188: @findex command-apropos
        !          2189: @cindex apropos
        !          2190:   A more sophisticated sort of question to ask is, ``What are the commands
        !          2191: for working with files?''  For this, type @kbd{C-h a file @key{RET}}, which
        !          2192: displays a list of all command names that contain @samp{file}, such as
        !          2193: @code{copy-file}, @code{find-file}, and so on.  With each command name
        !          2194: appears a brief description of how to use the command, and what keys you
        !          2195: can currently invoke it with.  For example, it would say that you can
        !          2196: invoke @code{find-file} by typing @kbd{C-x C-f}.  The @kbd{a} in @kbd{C-h
        !          2197: a} stands for `Apropos'; @kbd{C-h a} runs the Lisp function
        !          2198: @code{command-apropos}.@refill
        !          2199: 
        !          2200:   Because @kbd{C-h a} looks only for functions whose names contain the
        !          2201: string which you specify, you must use ingenuity in choosing substrings.
        !          2202: If you are looking for commands for killing backwards and @kbd{C-h a
        !          2203: kill-backwards @key{RET}} doesn't reveal any, don't give up.  Try just
        !          2204: @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}.  Be persistent.
        !          2205: Pretend you are playing Adventure.
        !          2206: 
        !          2207:   Here is a set of arguments to give to @kbd{C-h a} that covers many
        !          2208: classes of Emacs commands, since there are strong conventions for naming
        !          2209: the standard Emacs commands.  By giving you a feel for the naming
        !          2210: conventions, this set should also serve to aid you in developing a
        !          2211: technique for picking @code{apropos} strings.
        !          2212: 
        !          2213: @quotation
        !          2214: char, line, word, sentence, paragraph, region, page, sexp, list, defun,
        !          2215: buffer, screen, window, file, dir, register, mode,
        !          2216: beginning, end, forward, backward, next, previous, up, down, search, goto,
        !          2217: kill, delete, mark, insert, yank, fill, indent, case,
        !          2218: change, set, what, list, find, view, describe.
        !          2219: @end quotation
        !          2220: 
        !          2221: @findex apropos
        !          2222:   To list all Lisp symbols that contain a match for a regexp, not just
        !          2223: the ones that are defined as commands, use the command @kbd{M-x apropos}
        !          2224: instead of @kbd{C-h a}.
        !          2225: 
        !          2226: @section Other Help Commands
        !          2227: 
        !          2228: @kindex C-h l
        !          2229: @findex view-lossage
        !          2230:   If something surprising happens, and you are not sure what commands you
        !          2231: typed, use @kbd{C-h l} (@code{view-lossage}).  @kbd{C-h l} prints the last
        !          2232: 100 command characters you typed in.  If you see commands that you don't
        !          2233: know, you can use @kbd{C-h c} to find out what they do.
        !          2234: 
        !          2235: @kindex C-h m
        !          2236: @findex describe-mode
        !          2237:   Emacs has several major modes, each of which redefines a few keys and
        !          2238: makes a few other changes in how editing works.  @kbd{C-h m} (@code{describe-mode})
        !          2239: prints documentation on the current major mode, which normally describes
        !          2240: all the commands that are changed in this mode.
        !          2241: 
        !          2242: @kindex C-h b
        !          2243: @findex describe-bindings
        !          2244:   @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
        !          2245: (@code{describe-syntax}) present other information about the current
        !          2246: Emacs mode.  @kbd{C-h b} displays a list of all the key bindings now
        !          2247: in effect; the local bindings of the current major mode first,
        !          2248: followed by the global bindings (@pxref{Key Bindings}).  @kbd{C-h s}
        !          2249: displays the contents of the syntax table, with explanations of each
        !          2250: character's syntax (@pxref{Syntax}).@refill
        !          2251: 
        !          2252: @kindex C-h i
        !          2253: @findex info
        !          2254: @kindex C-h n
        !          2255: @findex view-emacs-news
        !          2256: @kindex C-h t
        !          2257: @findex help-with-tutorial
        !          2258: @kindex C-h C-c
        !          2259: @findex describe-copying
        !          2260: @kindex C-h C-d
        !          2261: @findex describe-distribution
        !          2262: @kindex C-h C-w
        !          2263: @findex describe-no-warranty
        !          2264:   The other @kbd{C-h} options display various files of useful information.
        !          2265: @kbd{C-h C-w} displays the full details on the complete absence of warranty
        !          2266: for GNU Emacs.  @kbd{C-h n} (@code{view-emacs-news}) displays the file
        !          2267: @file{emacs/etc/NEWS}, which contains documentation on Emacs changes
        !          2268: arranged chronologically.  @kbd{C-h t} (@code{help-with-tutorial}) displays
        !          2269: the learn-by-doing Emacs tutorial.  @kbd{C-h i} (@code{info}) runs the Info
        !          2270: program, which is used for browsing through structured documentation files.
        !          2271: @kbd{C-h C-c} (@code{describe-copying}) displays the file
        !          2272: @file{emacs/etc/COPYING}, which tells you the conditions you must obey in
        !          2273: distributing copies of Emacs.  @kbd{C-h C-d} (@code{describe-distribution})
        !          2274: displays the file @file{emacs/etc/DISTRIB}, which tells you how you can
        !          2275: order a copy of the latest version of Emacs.@refill
        !          2276: 
        !          2277: @node Mark, Killing, Help, Top
        !          2278: @chapter The Mark and the Region
        !          2279: @cindex mark
        !          2280: @cindex region
        !          2281: 
        !          2282:   There are many Emacs commands which operate on an arbitrary contiguous
        !          2283: part of the current buffer.  To specify the text for such a command to
        !          2284: operate on, you set @dfn{the mark} at one end of it, and move point to the
        !          2285: other end.  The text between point and the mark is called @dfn{the region}.
        !          2286: You can move point or the mark to adjust the boundaries of the region.  It
        !          2287: doesn't matter which one is set first chronologically, or which one comes
        !          2288: earlier in the text.
        !          2289: 
        !          2290:   Once the mark has been set, it remains until it is set again at another
        !          2291: place.  The mark remains fixed with respect to the preceding character if
        !          2292: text is inserted or deleted in the buffer.  Each Emacs buffer has its own
        !          2293: mark, so that when you return to a buffer that had been selected
        !          2294: previously, it has the same mark it had before.
        !          2295: 
        !          2296:   Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
        !          2297: @kbd{M-x insert-buffer}, position the mark at one end of the inserted
        !          2298: text---the opposite end from where point is positioned, so that the region
        !          2299: contains the text just inserted.
        !          2300: 
        !          2301: @menu
        !          2302: * Mark Ring::
        !          2303: 
        !          2304:   Aside from delimiting the region, the mark is also useful for remembering
        !          2305: a spot that you may want to go back to.  To make this feature more useful,
        !          2306: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}.
        !          2307: @end menu
        !          2308: 
        !          2309:   Here are some commands for setting the mark:
        !          2310: 
        !          2311: @c WideCommands
        !          2312: @table @kbd
        !          2313: @item C-@key{SPC}
        !          2314: Set the mark where point is (@code{set-mark-command}).
        !          2315: @item C-@@
        !          2316: The same.
        !          2317: @item C-x C-x
        !          2318: Interchange mark and point (@code{exchange-point-and-mark}).
        !          2319: @item M-@@
        !          2320: Set mark after end of next word (@code{mark-word}).  This command and
        !          2321: the following one do not move point.
        !          2322: @item C-M-@@
        !          2323: Set mark after end of next Lisp expression (@code{mark-sexp}).
        !          2324: @item M-h
        !          2325: Put region around current paragraph (@code{mark-paragraph}).
        !          2326: @item C-M-h
        !          2327: Put region around current Lisp defun (@code{mark-defun}).
        !          2328: @item C-x h
        !          2329: Put region around entire buffer (@code{mark-whole-buffer}).
        !          2330: @item C-x C-p
        !          2331: Put region around current page (@code{mark-page}).
        !          2332: @end table
        !          2333: 
        !          2334:   For example, if you wish to convert part of the buffer to all upper-case,
        !          2335: you can use the @kbd{C-x C-u} (@code{upcase-region}) command, which operates
        !          2336: on the text in the region.  You can first go to the beginning of the text
        !          2337: to be capitalized, type @kbd{C-@key{SPC}} to put the mark there, move to
        !          2338: the end, and then type @kbd{C-x C-u}.  Or, you can set the mark at the end
        !          2339: of the text, move to the beginning, and then type @kbd{C-x C-u}.  Most
        !          2340: commands that operate on the text in the region have the word @code{region}
        !          2341: in their names.
        !          2342: 
        !          2343: @kindex C-SPC
        !          2344: @findex set-mark-command
        !          2345:   The most common way to set the mark is with the @kbd{C-@key{SPC}} command
        !          2346: (@code{set-mark-command}).  This sets the mark where point is.  Then you
        !          2347: can move point away, leaving the mark behind.  It is actually incorrect to
        !          2348: speak of the character @kbd{C-@key{SPC}}; there is no such character.  When
        !          2349: you type @key{SPC} while holding down @key{CTRL}, what you get on most
        !          2350: terminals is the character @kbd{C-@@}.  This is the key actually bound to
        !          2351: @code{set-mark-command}.  But unless you are unlucky enough to have a
        !          2352: terminal where typing @kbd{C-@key{SPC}} does not produce @kbd{C-@@}, you
        !          2353: might as well think of this character as @kbd{C-@key{SPC}}.
        !          2354: 
        !          2355: @kindex C-x C-x
        !          2356: @findex exchange-point-and-mark
        !          2357:   Since terminals have only one cursor, there is no way for Emacs to show
        !          2358: you where the mark is located.  You have to remember.  The usual solution
        !          2359: to this problem is to set the mark and then use it soon, before you forget
        !          2360: where it is.  But you can see where the mark is with the command @kbd{C-x
        !          2361: C-x} (@code{exchange-point-and-mark}) which puts the mark where point was and
        !          2362: point where the mark was.  The extent of the region is unchanged, but the
        !          2363: cursor and point are now at the previous location of the mark.
        !          2364: 
        !          2365:   @kbd{C-x C-x} is also useful when you are satisfied with the location of
        !          2366: point but want to move the mark; do @kbd{C-x C-x} to put point there and
        !          2367: then you can move it.  A second use of @kbd{C-x C-x}, if necessary, puts
        !          2368: the mark at the new location with point back at its original location.
        !          2369: 
        !          2370: @section Operating on the Region
        !          2371: 
        !          2372:   Once you have created an active region, you can do many things to
        !          2373: the text in it:
        !          2374: @itemize @bullet
        !          2375: @item
        !          2376: Kill it with @kbd{C-w} (@pxref{Killing}).
        !          2377: @item
        !          2378: Save it in a register with @kbd{C-x x} (@pxref{Registers}).
        !          2379: @item
        !          2380: Save it in a buffer or a file (@pxref{Accumulating Text}).
        !          2381: @item
        !          2382: Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} @*(@pxref{Case}).
        !          2383: @item
        !          2384: Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
        !          2385: @item
        !          2386: Fill it as text with @kbd{M-g} (@pxref{Filling}).
        !          2387: @item
        !          2388: Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
        !          2389: @item
        !          2390: Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}).
        !          2391: @end itemize
        !          2392: 
        !          2393: @section Commands to Mark Textual Objects
        !          2394: 
        !          2395: @kindex M-@@
        !          2396: @kindex C-M-@@
        !          2397: @findex mark-word
        !          2398: @findex mark-sexp
        !          2399:   There are commands for placing the mark on the other side of a certain
        !          2400: object such as a word or a list, without having to move there first.
        !          2401: @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word,
        !          2402: while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp
        !          2403: expression.  These characters allow you to save a little typing or
        !          2404: redisplay, sometimes.
        !          2405: 
        !          2406: @kindex M-h
        !          2407: @kindex C-M-h
        !          2408: @kindex C-x C-p
        !          2409: @kindex C-x h
        !          2410: @findex mark-paragraph
        !          2411: @findex mark-defun
        !          2412: @findex mark-page
        !          2413: @findex mark-whole-buffer
        !          2414:    Other commands set both point and mark, to delimit an object in the
        !          2415: buffer.  @kbd{M-h} (@code{mark-paragraph}) moves point to the beginning of
        !          2416: the paragraph that surrounds or follows point, and puts the mark at the end
        !          2417: of that paragraph (@pxref{Paragraphs}).  @kbd{M-h} does all that's
        !          2418: necessary if you wish to indent, case-convert, or kill a whole paragraph.
        !          2419: @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the mark
        !          2420: after the current or following defun (@pxref{Defuns}).  @kbd{C-x C-p}
        !          2421: (@code{mark-page}) puts point before the current page (or the next or
        !          2422: previous, according to the argument), and mark at the end (@pxref{Pages}).
        !          2423: The mark goes after the terminating page delimiter (to include it), while
        !          2424: point goes after the preceding page delimiter (to exclude it).  Finally,
        !          2425: @kbd{C-x h} (@code{mark-whole}) sets up the entire buffer as the region, by
        !          2426: putting point at the beginning and the mark at the end.
        !          2427: 
        !          2428: @node Mark Ring,, Mark, Mark
        !          2429: @section The Mark Ring
        !          2430: 
        !          2431: @kindex C-u C-SPC
        !          2432: @cindex mark ring
        !          2433: @kindex C-u C-@@
        !          2434:   Aside from delimiting the region, the mark is also useful for remembering
        !          2435: a spot that you may want to go back to.  To make this feature more useful,
        !          2436: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}.
        !          2437: Most commands that set the mark push the old mark onto this ring.  To
        !          2438: return to a marked location, use @kbd{C-u C-@@} (or @kbd{C-u C-@key{SPC}});
        !          2439: this is the command @code{set-mark-command} given a numeric argument.  This
        !          2440: moves point to where the mark was, and restores the mark from the ring of
        !          2441: former marks.  So repeated use of this command moves point to all of the
        !          2442: old marks on the ring, one by one.  Enough uses of @kbd{C-u C-@@} bring
        !          2443: point back to where it was originally.
        !          2444: 
        !          2445:   Each buffer has its own mark ring.  All editing commands that use the
        !          2446: mark ring use the current buffer's mark ring.  In particular, @kbd{C-u
        !          2447: C-@key{SPC}} always stays in the same buffer.
        !          2448: 
        !          2449:   Many commands that can move long distances, such as @kbd{M-<}
        !          2450: (@code{beginning-of-buffer}), start by setting the mark and saving the old
        !          2451: mark on the mark ring, just as a way of making it possible for you to move
        !          2452: to where point was before the command.  This is to make it easier for you
        !          2453: to move back later.  Searches do this except when they do not actually move
        !          2454: point.  You can tell when a command sets the mark because @samp{Mark Set}
        !          2455: is printed in the echo area.
        !          2456: 
        !          2457: @vindex mark-ring-max
        !          2458:   The variable @code{mark-ring-max} is the maximum number of entries to
        !          2459: keep in the mark ring.  If that many entries exist and another one is
        !          2460: pushed, the last one in the list is discarded.  Repeating @kbd{C-u
        !          2461: C-@key{SPC}} circulates through the limited number of entries that are
        !          2462: currently in the ring.
        !          2463: 
        !          2464: @vindex mark-ring
        !          2465:   The variable @code{mark-ring} holds the mark ring itself, as a list of
        !          2466: marker objects in the order most recent first.
        !          2467: 
        !          2468: @iftex
        !          2469: @chapter Killing and Moving Text
        !          2470: 
        !          2471:   @dfn{Killing} means erasing text and copying it into the @dfn{kill ring},
        !          2472: from which it can be retrieved by @dfn{yanking} it.
        !          2473: 
        !          2474:   The commonest way of moving or copying text with Emacs is to kill it and
        !          2475: later yank it in one or more places.  This is very safe because all the
        !          2476: text killed recently is remembered, and it is versatile, because the many
        !          2477: commands for killing syntactic units can also be used for moving those
        !          2478: units.  There are also other ways of copying text for special purposes.
        !          2479: 
        !          2480:   Emacs has only one kill ring, so you can kill text in one buffer and yank
        !          2481: it in another buffer.
        !          2482: 
        !          2483: @end iftex
        !          2484: 
        !          2485: @node Killing, Yanking, Mark, Top
        !          2486: @section Deletion and Killing
        !          2487: @findex delete-char
        !          2488: @c ??? Should be backward-delete-char
        !          2489: @findex delete-backward-char
        !          2490: 
        !          2491: @cindex killing
        !          2492: @cindex deletion
        !          2493: @kindex C-d
        !          2494: @kindex DEL
        !          2495:   Most commands which erase text from the buffer save it so that you can
        !          2496: get it back if you change your mind, or move or copy it to other parts of
        !          2497: the buffer.  These commands are known as @dfn{kill} commands.  The rest of
        !          2498: the commands that erase text do not save it; they are known as @dfn{delete}
        !          2499: commands.  (This distinction is made only for erasure of text in the
        !          2500: buffer.)
        !          2501: 
        !          2502:   The delete commands include @kbd{C-d} (@code{delete-char}) and
        !          2503: @key{DEL} (@code{delete-backward-char}), which delete only one character at
        !          2504: a time, and those commands that delete only spaces or newlines.  Commands
        !          2505: that can destroy significant amounts of nontrivial data generally kill.
        !          2506: The commands' names and individual descriptions use the words @samp{kill}
        !          2507: and @samp{delete} to say which they do.  If you do a kill or delete command
        !          2508: by mistake, you can use the @kbd{C-x u} (@code{undo}) command to undo it
        !          2509: (@pxref{Undo}).@refill
        !          2510: 
        !          2511: @subsection Deletion
        !          2512: 
        !          2513: @table @kbd
        !          2514: @item C-d
        !          2515: Delete next character (@code{delete-char}).
        !          2516: @item @key{DEL}
        !          2517: Delete previous character (@code{delete-backward-char}).
        !          2518: @item M-\
        !          2519: Delete spaces and tabs around point (@code{delete-horizontal-space}).
        !          2520: @item M-@key{SPC}
        !          2521: Delete spaces and tabs around point, leaving one space
        !          2522: (@code{just-one-space}).
        !          2523: @item C-x C-o
        !          2524: Delete blank lines around the current line (@code{delete-blank-lines}).
        !          2525: @item M-^
        !          2526: Join two lines by deleting the intervening newline, and any indentation
        !          2527: following it (@code{delete-indentation}).
        !          2528: @end table
        !          2529: 
        !          2530:   The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
        !          2531: @key{DEL} (@code{delete-backward-char}).  @kbd{C-d} deletes the character
        !          2532: after point, the one the cursor is ``on top of''.  Point doesn't move.
        !          2533: @key{DEL} deletes the character before the cursor, and moves point back.
        !          2534: Newlines can be deleted like any other characters in the buffer; deleting a
        !          2535: newline joins two lines.  Actually, @kbd{C-d} and @key{DEL} aren't always
        !          2536: delete commands; if given an argument, they kill instead, since they can
        !          2537: erase more than one character this way.
        !          2538: 
        !          2539: @kindex M-\
        !          2540: @findex delete-horizontal-space
        !          2541: @kindex M-SPC
        !          2542: @findex just-one-space
        !          2543: @kindex C-x C-o
        !          2544: @findex delete-blank-lines
        !          2545: @kindex M-^
        !          2546: @findex delete-indentation
        !          2547:   The other delete commands are those which delete only formatting
        !          2548: characters: spaces, tabs and newlines.  @kbd{M-\} (@code{delete-horizontal-space})
        !          2549: deletes all the spaces and tab characters before and after point.
        !          2550: @kbd{M-@key{SPC}} (@code{just-one-space}) does likewise but leaves a single
        !          2551: space after point, regardless of the number of spaces that existed
        !          2552: previously (even zero).
        !          2553: 
        !          2554:   @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after
        !          2555: the current line, and if the current line is blank deletes all blank lines
        !          2556: preceding the current line as well (leaving one blank line, the current
        !          2557: line).  @kbd{M-^} (@code{delete-indentation}) joins the current line and
        !          2558: the previous line, or the current line and the next line if given an
        !          2559: argument, by deleting a newline and all surrounding spaces, possibly
        !          2560: leaving a single space.  @xref{Indentation,M-^}.
        !          2561: 
        !          2562: @subsection Killing by Lines
        !          2563: 
        !          2564: @table @kbd
        !          2565: @item C-k
        !          2566: Kill rest of line or one or more lines (@code{kill-line}).
        !          2567: @end table
        !          2568: 
        !          2569: @kindex C-k
        !          2570: @findex kill-line
        !          2571:   The simplest kill command is @kbd{C-k}.  If given at the beginning of a
        !          2572: line, it kills all the text on the line, leaving it blank.  If given on a
        !          2573: blank line, the blank line disappears.  As a consequence, if you go to the
        !          2574: front of a non-blank line and type @kbd{C-k} twice, the line disappears
        !          2575: completely.
        !          2576: 
        !          2577:   More generally, @kbd{C-k} kills from point up to the end of the line,
        !          2578: unless it is at the end of a line.  In that case it kills the newline
        !          2579: following the line, thus merging the next line into the current one.
        !          2580: Invisible spaces and tabs at the end of the line are ignored when deciding
        !          2581: which case applies, so if point appears to be at the end of the line, you
        !          2582: can be sure the newline will be killed.
        !          2583: 
        !          2584:   If @kbd{C-k} is given a positive argument, it kills that many lines and
        !          2585: the newlines that follow them (however, text on the current line before
        !          2586: point is spared).  With a negative argument, it kills back to a number of
        !          2587: line beginnings.  An argument of -2 means kill back to the second line
        !          2588: beginning.  If point is at the beginning of a line, that line beginning
        !          2589: doesn't count, so @kbd{C-u - 2 C-k} with point at the front of a line kills
        !          2590: the two previous lines.
        !          2591: 
        !          2592:   @kbd{C-k} with an argument of zero kills all the text before point on the
        !          2593: current line.
        !          2594: 
        !          2595: @subsection Other Kill Commands
        !          2596: @findex kill-line
        !          2597: @findex kill-region
        !          2598: @findex kill-word
        !          2599: @findex backward-kill-word
        !          2600: @findex kill-sexp
        !          2601: @findex kill-sentence
        !          2602: @findex backward-kill-sentence
        !          2603: @kindex M-d
        !          2604: @kindex M-DEL
        !          2605: @kindex C-M-k
        !          2606: @kindex C-x DEL
        !          2607: @kindex M-k
        !          2608: @kindex C-k
        !          2609: @kindex C-w
        !          2610: 
        !          2611: @c DoubleWideCommands
        !          2612: @table @kbd
        !          2613: @item C-w
        !          2614: Kill region (from point to the mark) (@code{kill-region}).
        !          2615: @item M-d
        !          2616: Kill word (@code{kill-word}).
        !          2617: @item M-@key{DEL}
        !          2618: Kill word backwards (@code{backward-kill-word}).
        !          2619: @item C-x @key{DEL}
        !          2620: Kill back to beginning of sentence (@code{backward-kill-sentence}).
        !          2621: @xref{Sentences}.
        !          2622: @item M-k
        !          2623: Kill to end of sentence (@code{kill-sentence}).
        !          2624: @item C-M-k
        !          2625: Kill sexp (@pxref{Lists}) (@code{kill-sexp}).
        !          2626: @item M-z @var{char}
        !          2627: Kill up to next occurrence of @var{char} (@code{zap-to-char}).
        !          2628: @end table
        !          2629: 
        !          2630:   A kill command which is very general is @kbd{C-w} (@code{kill-region}),
        !          2631: which kills everything between point and the mark.  With this command, you
        !          2632: can kill any contiguous sequence of characters, if you first set the mark
        !          2633: at one end of them and go to the other end.
        !          2634: 
        !          2635: @kindex M-z
        !          2636: @findex zap-to-char
        !          2637:   A convenient way of killing is combined with searching: @kbd{M-z}
        !          2638: (@code{zap-to-char}) reads a character and kills from point up to (but not
        !          2639: including) the next occurrence of that character in the buffer.  If there
        !          2640: is no next occurrence, killing goes to the end of the buffer.  A numeric
        !          2641: argument acts as a repeat count.  A negative argument means to search
        !          2642: backward and kill text before point.
        !          2643: 
        !          2644:   Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
        !          2645: @kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
        !          2646: sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
        !          2647: (@pxref{Sentences}).@refill
        !          2648: 
        !          2649: @node Yanking, Accumulating Text, Killing, Top
        !          2650: @section Yanking
        !          2651: @cindex moving text
        !          2652: @cindex kill ring
        !          2653: @cindex yanking
        !          2654: 
        !          2655:   @dfn{Yanking} is getting back text which was killed.  The usual way to
        !          2656: move or copy text is to kill it and then yank it one or more times.
        !          2657: 
        !          2658: @table @kbd
        !          2659: @item C-y
        !          2660: Yank last killed text (@code{yank}).
        !          2661: @item M-y
        !          2662: Replace re-inserted killed text with the previously killed text
        !          2663: (@code{yank-pop}).
        !          2664: @item M-w
        !          2665: Save region as last killed text without actually killing it
        !          2666: (@code{copy-region-as-kill}).
        !          2667: @item C-M-w
        !          2668: Append next kill to last batch of killed text (@code{append-next-kill}).
        !          2669: @end table
        !          2670: 
        !          2671: @kindex C-y
        !          2672: @findex Yank
        !          2673:   All killed text is recorded in the @dfn{kill ring}, a list of blocks of
        !          2674: text that have been killed.  There is only one kill ring, used in all
        !          2675: buffers, so you can kill text in one buffer and yank it in another buffer.
        !          2676: This is the usual way to move text from one file to another.
        !          2677: (@xref{Accumulating Text}, for some other ways.)
        !          2678: 
        !          2679:   The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
        !          2680: kill.  It leaves the cursor at the end of the text.  It sets the mark at
        !          2681: the beginning of the text.  @xref{Mark}.
        !          2682: 
        !          2683:   @kbd{C-u C-y} leaves the cursor in front of the text, and sets the mark
        !          2684: after it.  This is only if the argument is specified with just a @kbd{C-u},
        !          2685: precisely.  Any other sort of argument, including @kbd{C-u} and digits, has
        !          2686: an effect described below (under ``Yanking Earlier Kills'').
        !          2687: 
        !          2688: @kindex M-w
        !          2689: @findex copy-region-as-kill
        !          2690:   If you wish to copy a block of text, you might want to use @kbd{M-w}
        !          2691: (@code{copy-region-as-kill}), which copies the region into the kill ring
        !          2692: without removing it from the buffer.  This is approximately equivalent to
        !          2693: @kbd{C-w} followed by @kbd{C-y}, except that @kbd{M-w} does not mark the
        !          2694: buffer as ``modified'' and does not temporarily change the screen.
        !          2695: 
        !          2696: @subsection Appending Kills
        !          2697: 
        !          2698:   Normally, each kill command pushes a new block onto the kill ring.
        !          2699: However, two or more kill commands in a row combine their text into a
        !          2700: single entry, so that a single @kbd{C-y} gets it all back as it was before
        !          2701: it was killed.  This means that you don't have to kill all the text in one
        !          2702: command; you can keep killing line after line, or word after word, until
        !          2703: you have killed it all, and you can still get it all back at once.  (Thus
        !          2704: we join television in leading people to kill thoughtlessly.)
        !          2705: 
        !          2706:   Commands that kill forward from point add onto the end of the previous
        !          2707: killed text.  Commands that kill backward from point add onto the
        !          2708: beginning.  This way, any sequence of mixed forward and backward kill
        !          2709: commands puts all the killed text into one entry without rearrangement.
        !          2710: Numeric arguments do not break the sequence of appending kills.  For
        !          2711: example, suppose the buffer contains
        !          2712: 
        !          2713: @example
        !          2714: This is the first
        !          2715: line of sample text
        !          2716: and here is the third.
        !          2717: @end example
        !          2718: 
        !          2719: @noindent
        !          2720: with point at the beginning of the second line.  If you type @kbd{C-k C-u 2
        !          2721: M-@key{DEL} C-k}, the first @kbd{C-k} kills the text @samp{line of sample
        !          2722: text}, @kbd{C-u 2 M-@key{DEL}} kills @samp{the first} with the newline that
        !          2723: followed it, and the second @kbd{C-k} kills the newline after the second
        !          2724: line.  The result is that the buffer contains @samp{This is and here is the
        !          2725: third.} and a single kill entry contains @samp{the first@key{RET}line of
        !          2726: sample text@key{RET}}---all the killed text, in its original order.
        !          2727: 
        !          2728: @kindex C-M-w
        !          2729: @findex append-next-kill
        !          2730:   If a kill command is separated from the last kill command by other
        !          2731: commands (not just numeric arguments), it starts a new entry on the kill
        !          2732: ring.  But you can force it to append by first typing the command
        !          2733: @kbd{C-M-w} (@code{append-next-kill}) in front of it.  The @kbd{C-M-w}
        !          2734: tells the following command, if it is a kill command, to append the text it
        !          2735: kills to the last killed text, instead of starting a new entry.  With
        !          2736: @kbd{C-M-w}, you can kill several separated pieces of text and accumulate
        !          2737: them to be yanked back in one place.@refill
        !          2738: 
        !          2739: @subsection Yanking Earlier Kills
        !          2740: 
        !          2741: @kindex M-y
        !          2742: @findex yank-pop
        !          2743:   To recover killed text that is no longer the most recent kill, you need
        !          2744: the @kbd{Meta-y} (@code{yank-pop}) command.  @kbd{M-y} can be used only
        !          2745: after a @kbd{C-y} or another @kbd{M-y}.  It takes the text previously
        !          2746: yanked and replaces it with the text from an earlier kill.  So, to recover
        !          2747: the text of the next-to-the-last kill, you first use @kbd{C-y} to recover
        !          2748: the last kill, and then use @kbd{M-y} to replace it with the previous
        !          2749: kill.@refill
        !          2750: 
        !          2751:   You can think in terms of a ``last yank'' pointer which points at an item
        !          2752: in the kill ring.  Each time you kill, the ``last yank'' pointer moves to
        !          2753: the newly made item at the front of the ring.  @kbd{C-y} yanks the item
        !          2754: which the ``last yank'' pointer points to.  @kbd{M-y} moves the ``last
        !          2755: yank'' pointer to a different item, and the text in the buffer changes to
        !          2756: match.  Enough @kbd{M-y} commands can move the pointer to any item in the
        !          2757: ring, so you can get any item into the buffer.  Eventually the pointer
        !          2758: reaches the end of the ring; the next @kbd{M-y} moves it to the first item
        !          2759: again.
        !          2760: 
        !          2761:   @kbd{M-y} can take a numeric argument, which tells it how many items to
        !          2762: advance the ``last yank'' pointer by.  A negative argument moves the
        !          2763: pointer toward the front of the ring; from the front of the ring, it moves
        !          2764: to the last entry and starts moving forward from there.
        !          2765: 
        !          2766:   Once the text you are looking for is brought into the buffer, you can
        !          2767: stop doing @kbd{M-y} commands and it will stay there.  It's just a copy of
        !          2768: the kill ring item, so editing it in the buffer does not change what's in
        !          2769: the ring.  As long as no new killing is done, the ``last yank'' pointer
        !          2770: remains at the same place in the kill ring, so repeating @kbd{C-y} will
        !          2771: yank another copy of the same old kill.
        !          2772: 
        !          2773:   If you know how many @kbd{M-y} commands it would take to find the
        !          2774: text you want, you can yank that text in one step using @kbd{C-y} with
        !          2775: a numeric argument.  @kbd{C-y} with an argument greater than one
        !          2776: restores the text the specified number of entries back in the kill
        !          2777: ring.  Thus, @kbd{C-u 2 C-y} gets the next to the last block of killed
        !          2778: text.  It is equivalent to @kbd{C-y M-y}.  @kbd{C-y} with a numeric
        !          2779: argument starts counting from the ``last yank'' pointer, and sets the
        !          2780: ``last yank'' pointer to the entry that it yanks.
        !          2781: 
        !          2782: @vindex kill-ring-max
        !          2783:   The length of the kill ring is controlled by the variable
        !          2784: @code{kill-ring-max}; no more than that many blocks of killed text are
        !          2785: saved.
        !          2786: 
        !          2787: @node Accumulating Text, Rectangles, Yanking, Top
        !          2788: @section Accumulating Text
        !          2789: @kindex C-x a
        !          2790: @findex append-to-buffer
        !          2791: @findex prepend-to-buffer
        !          2792: @findex copy-to-buffer
        !          2793: @findex append-to-file
        !          2794: 
        !          2795:   Usually we copy or move text by killing it and yanking it, but there are
        !          2796: other ways that are useful for copying one block of text in many places, or
        !          2797: for copying many scattered blocks of text into one place.
        !          2798: 
        !          2799:   You can accumulate blocks of text from scattered locations either into a
        !          2800: buffer or into a file if you like.  These commands are described here.  You
        !          2801: can also use Emacs registers for storing and accumulating text.
        !          2802: @xref{Registers}.
        !          2803: 
        !          2804: @table @kbd
        !          2805: @item C-x a
        !          2806: Append region to contents of specified buffer (@code{append-to-buffer}).
        !          2807: @item M-x prepend-to-buffer
        !          2808: Prepend region to contents of specified buffer.
        !          2809: @item M-x copy-to-buffer
        !          2810: Copy region into specified buffer, deleting that buffer's old contents.
        !          2811: @item M-x insert-buffer
        !          2812: Insert contents of specified buffer into current buffer at point.
        !          2813: @item M-x append-to-file
        !          2814: Append region to contents of specified file, at the end.
        !          2815: @end table
        !          2816: 
        !          2817:   To accumulate text into a buffer, use the command @kbd{C-x a @var{buffername}}
        !          2818: (@code{append-to-buffer}), which inserts a copy of the region into the
        !          2819: buffer @var{buffername}, at the location of point in that buffer.  If there
        !          2820: is no buffer with that name, one is created.  If you append text into a
        !          2821: buffer which has been used for editing, the copied text goes into the
        !          2822: middle of the text of the buffer, wherever point happens to be in it.
        !          2823: 
        !          2824:   Point in that buffer is left at the end of the copied text, so successive
        !          2825: uses of @kbd{C-x a} accumulate the text in the specified buffer in the same
        !          2826: order as they were copied.  Strictly speaking, @kbd{C-x a} does not always
        !          2827: append to the text already in the buffer; but if @kbd{C-x a} is the only
        !          2828: command used to alter a buffer, it does always append to the existing text
        !          2829: because point is always at the end.
        !          2830: 
        !          2831:   @kbd{M-x prepend-to-buffer} is just like @kbd{C-x a} except that point in
        !          2832: the other buffer is left before the copied text, so successive prependings
        !          2833: add text in reverse order.  @kbd{M-x copy-to-buffer} is similar except that
        !          2834: any existing text in the other buffer is deleted, so the buffer is left
        !          2835: containing just the text newly copied into it.
        !          2836: 
        !          2837:   You can retrieve the accumulated text from that buffer with @kbd{M-x
        !          2838: insert-buffer}; this too takes @var{buffername} as an argument.  It inserts
        !          2839: a copy of the text in buffer @var{buffername} into the selected buffer.
        !          2840: You could alternatively select the other buffer for editing, perhaps moving
        !          2841: text from it by killing or with @kbd{C-x a}.  @xref{Buffers}, for
        !          2842: background information on buffers.
        !          2843: 
        !          2844:   Instead of accumulating text within Emacs, in a buffer, you can append
        !          2845: text directly into a file with @kbd{M-x append-to-file}, which takes
        !          2846: @var{file-name} as an argument.  It adds the text of the region to the end
        !          2847: of the specified file.  The file is changed immediately on disk. This
        !          2848: command is normally used with files that are @i{not} being visited in
        !          2849: Emacs.  Using it on a file that Emacs is visiting can produce confusing
        !          2850: results, because the text inside Emacs for that file will not change
        !          2851: while the file itself changes.
        !          2852: 
        !          2853: @node Rectangles, Registers, Accumulating Text, Top
        !          2854: @section Rectangles
        !          2855: @cindex rectangles
        !          2856: 
        !          2857:   The rectangle commands affect rectangular areas of the text: all the
        !          2858: characters between a certain pair of columns, in a certain range of lines.
        !          2859: Commands are provided to kill rectangles, yank killed rectangles, clear
        !          2860: them out, or delete them.  Rectangle commands are useful with text in
        !          2861: multicolumnar formats, such as perhaps code with comments at the right,
        !          2862: or for changing text into or out of such formats.
        !          2863: 
        !          2864:   When you must specify a rectangle for a command to work on, you do
        !          2865: it by putting the mark at one corner and point at the opposite corner.
        !          2866: The rectangle thus specified is called the @dfn{region-rectangle}
        !          2867: because it is controlled about the same way the region is controlled.
        !          2868: But remember that a given combination of point and mark values can be
        !          2869: interpreted either as specifying a region or as specifying a
        !          2870: rectangle; it is up to the command that uses them to choose the
        !          2871: interpretation.
        !          2872: 
        !          2873: @table @kbd
        !          2874: @item M-x delete-rectangle
        !          2875: Delete the text of the region-rectangle, moving any following text on
        !          2876: each line leftward to the left edge of the region-rectangle.
        !          2877: @item M-x kill-rectangle
        !          2878: Similar, but also save the contents of the region-rectangle as the
        !          2879: ``last killed rectangle''.
        !          2880: @item M-x yank-rectangle
        !          2881: Yank the last killed rectangle with its upper left corner at point.
        !          2882: @item M-x open-rectangle
        !          2883: Insert blank space to fill the space of the region-rectangle.
        !          2884: The previous contents of the region-rectangle are pushed rightward.
        !          2885: @item M-x clear-rectangle
        !          2886: Clear the region-rectangle by replacing its contents with spaces.
        !          2887: @end table
        !          2888: 
        !          2889:   The rectangle operations fall into two classes: commands deleting and
        !          2890: moving rectangles, and commands for blank rectangles.
        !          2891: 
        !          2892: @findex delete-rectangle
        !          2893: @findex kill-rectangle
        !          2894:   There are two ways to delete a rectangle: you can discard its contents,
        !          2895: or save them as the ``last killed'' rectangle.  The commands for these
        !          2896: two ways are @kbd{M-x delete-rectangle} and @kbd{M-x kill-rectangle}.  In
        !          2897: any case, the portion of each line that falls inside the rectangle's
        !          2898: boundaries is deleted, causing following text (if any) on the line to move
        !          2899: left.
        !          2900: 
        !          2901:   Note that ``killing'' a rectangle is not killing in the usual sense; the
        !          2902: rectangle is not stored in the kill ring, but in a special place that
        !          2903: can only record the most recent rectangle killed.  This is because yanking
        !          2904: a rectangle is so different from yanking linear text that different yank
        !          2905: commands have to be used and yank-popping is hard to make sense of.
        !          2906: 
        !          2907:   Inserting a rectangle is the opposite of deleting one.  All you need to
        !          2908: specify is where to put the upper left corner; that is done by putting
        !          2909: point there.  The rectangle's first line is inserted there, the rectangle's
        !          2910: second line is inserted at a point one line vertically down, and so on.
        !          2911: The number of lines affected is determined by the height of the saved
        !          2912: rectangle.
        !          2913: 
        !          2914: @findex yank-rectangle
        !          2915:   To insert the last killed rectangle, type @kbd{M-x yank-rectangle}.
        !          2916: 
        !          2917: @findex open-rectangle
        !          2918: @findex clear-rectangle
        !          2919:   There are two commands for working with blank rectangles: @kbd{M-x
        !          2920: clear-rectangle} to blank out existing text, and @kbd{M-x open-rectangle}
        !          2921: to insert a blank rectangle.  Clearing a rectangle is equivalent to
        !          2922: deleting it and then inserting as blank rectangle of the same size.
        !          2923: 
        !          2924:   Rectangles can also be copied into and out of registers.
        !          2925: @xref{RegRect,,Rectangle Registers}.
        !          2926: 
        !          2927: @node Registers, Display, Rectangles, Top
        !          2928: @chapter Registers
        !          2929: @cindex registers
        !          2930: 
        !          2931:   Emacs @dfn{registers} are places you can save text or positions for
        !          2932: later use.  Text saved in a register can be copied into the buffer
        !          2933: once or many times; a position saved in a register is used by moving
        !          2934: point to that position.  Rectangles can also be copied into and out of
        !          2935: registers (@pxref{Rectangles}).
        !          2936: 
        !          2937:   Each register has a name, which is a single character.  It can store
        !          2938: either a piece of text or a position or a rectangle; only one of the three
        !          2939: at any given time.  Whatever you store in a register remains there until
        !          2940: you store something else in that register.
        !          2941: 
        !          2942: @menu
        !          2943: * RegPos::    Saving positions in registers.
        !          2944: * RegText::   Saving text in registers.
        !          2945: * RegRect::   Saving rectangles in registers.
        !          2946: @end menu
        !          2947: 
        !          2948: @table @kbd
        !          2949: @item M-x view-register @key{RET} @var{r}
        !          2950: Display a description of what register @var{r} contains.
        !          2951: @end table
        !          2952: 
        !          2953: @findex view-register
        !          2954:   @kbd{M-x view-register} reads a register name as an argument and then
        !          2955: displays the contents of the specified register.
        !          2956: 
        !          2957: @node RegPos, RegText, Registers, Registers
        !          2958: @section Saving Positions in Registers
        !          2959: 
        !          2960:   Saving a position records a spot in a buffer so that you can move
        !          2961: back there later.  Moving to a saved position reselects the buffer
        !          2962: and moves point to the spot.
        !          2963: 
        !          2964: @table @kbd
        !          2965: @item C-x / @var{r}
        !          2966: Save location of point in register @var{r} (@code{point-to-register}).
        !          2967: @item C-x j @var{r}
        !          2968: Jump to the location saved in register @var{r} (@code{register-to-point}).
        !          2969: @end table
        !          2970: 
        !          2971: @kindex C-x /
        !          2972: @findex point-to-register
        !          2973:   To save the current location of point in a register, choose a name
        !          2974: @var{r} and type @kbd{C-x / @var{r}}.  The register @var{r} retains
        !          2975: the location thus saved until you store something else in that
        !          2976: register.@refill
        !          2977: 
        !          2978: @kindex C-x j
        !          2979: @findex register-to-point
        !          2980:   The command @kbd{C-x j @var{r}} moves point to the location recorded
        !          2981: in register @var{r}.  The register is not affected; it continues to
        !          2982: record the same location.  You can jump to the same position using the
        !          2983: same register any number of times.
        !          2984: 
        !          2985: @node RegText, RegRect, RegPos, Registers
        !          2986: @section Saving Text in Registers
        !          2987: 
        !          2988:   When you want to insert a copy of the same piece of text frequently, it
        !          2989: may be impractical to use the kill ring, since each subsequent kill moves
        !          2990: the piece of text farther down on the ring.  It becomes hard to keep track
        !          2991: of what argument is needed to retrieve the same text with @kbd{C-y}.  An
        !          2992: alternative is to store the text in a register with @kbd{C-x x}
        !          2993: (@code{copy-to-register}) and then retrieve it with @kbd{C-x g}
        !          2994: (@code{insert-register}).
        !          2995: 
        !          2996: @table @kbd
        !          2997: @item C-x x @var{r}
        !          2998: Copy region into register @var{r} (@code{copy-to-register}).
        !          2999: @item C-x g @var{r}
        !          3000: Insert text contents of register @var{r} (@code{insert-register}).
        !          3001: @end table
        !          3002: 
        !          3003: @kindex C-x x
        !          3004: @kindex C-x g
        !          3005: @findex copy-to-register
        !          3006: @findex insert-register
        !          3007:   @kbd{C-x x @var{r}} stores a copy of the text of the region into the
        !          3008: register named @var{r}.  Given a numeric argument, @kbd{C-x x} deletes the
        !          3009: text from the buffer as well.
        !          3010: 
        !          3011:   @kbd{C-x g @var{r}} inserts in the buffer the text from register @var{r}.
        !          3012: Normally it leaves point before the text and places the mark after, but
        !          3013: with a numeric argument it puts point after the text and the mark before.
        !          3014: 
        !          3015: @node RegRect,, RegText, Registers
        !          3016: @section Saving Rectangles in Registers
        !          3017: @cindex rectangle
        !          3018: 
        !          3019:   A register can contain a rectangle instead of linear text.  The rectangle
        !          3020: is represented as a list of strings.  @xref{Rectangles}, for basic
        !          3021: information on rectangles and how rectangles in the buffer are specified.
        !          3022: 
        !          3023: @table @kbd
        !          3024: @item C-x r @var{r}
        !          3025: Copy the region-rectangle into register @var{r} @*(@code{copy-region-to-rectangle}).
        !          3026: With numeric argument, delete it as well.
        !          3027: @item C-x g @var{r}
        !          3028: Insert the rectangle stored in register @var{r} (if it contains a
        !          3029: rectangle) (@code{insert-register}).
        !          3030: @end table
        !          3031: 
        !          3032:   The @kbd{C-x g} command inserts linear text if the register contains
        !          3033: that, or inserts a rectangle if the register contains one.
        !          3034: 
        !          3035: @node Display, Search, Registers, Top
        !          3036: @chapter Controlling the Display
        !          3037: @cindex scrolling
        !          3038: 
        !          3039:   Since only part of a large buffer fits in the window, Emacs tries to show
        !          3040: the part that is likely to be interesting.  The display control commands
        !          3041: allow you to ask to see a different part of the text.  This is also known
        !          3042: as @dfn{scrolling}.
        !          3043: 
        !          3044:   If a buffer contains text that is too large to fit entirely within a
        !          3045: window that is displaying the buffer, Emacs shows a contiguous section of
        !          3046: the text.  The section shown always contains point.  As you change the
        !          3047: text, Emacs always tries to keep the same position in the text at the top
        !          3048: of the window.  A new position moves to the top of the window only if this
        !          3049: is necessary to keep point visible, or if you request it explicitly with a
        !          3050: display control command.
        !          3051: 
        !          3052: @table @kbd
        !          3053: @item C-l
        !          3054: Clear screen and redisplay, scrolling the selected window to center
        !          3055: point vertically within it (@code{recenter}).
        !          3056: @item C-v
        !          3057: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
        !          3058: @item M-v
        !          3059: Scroll backward (@code{scroll-down}).
        !          3060: @item C-x <
        !          3061: Scroll text in current window to the left (@code{scroll-left}).
        !          3062: @item C-x >
        !          3063: Scroll to the right (@code{scroll-right}).
        !          3064: @item M-r
        !          3065: Move point to the text at a given vertical position within the window
        !          3066: (@code{move-to-window-line}).
        !          3067: @item C-x $
        !          3068: Make deeply indented lines invisible (@code{set-selective-display}).
        !          3069: @end table
        !          3070: 
        !          3071: @kindex C-l
        !          3072: @findex recenter
        !          3073:   The basic display control command is @kbd{C-l} (@code{recenter}).  In its
        !          3074: simplest form, with no argument, it clears the entire screen and redisplays
        !          3075: all windows, scrolling the selected window so that point is halfway down
        !          3076: from the top of the window.  Other windows are cleared and redisplayed, but
        !          3077: not scrolled.
        !          3078: 
        !          3079:   @kbd{C-l} with a numeric argument does not clear the screen; it does
        !          3080: nothing except scroll the selected window as specified by the argument.
        !          3081: With a positive argument @var{n}, it repositions text to put point @var{n}
        !          3082: lines down from the top.  An argument of zero puts point on the very top
        !          3083: line.  Point does not move with respect to the text; rather, the text and
        !          3084: point move rigidly on the screen.  @kbd{C-l} with a negative argument puts
        !          3085: point that many lines from the bottom of the window.  For example, @kbd{C-u
        !          3086: - 1 C-l} puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five
        !          3087: lines from the bottom.
        !          3088: 
        !          3089: @kindex C-v
        !          3090: @kindex M-v
        !          3091: @findex scroll-up
        !          3092: @findex scroll-down
        !          3093:   The @dfn{scrolling} commands @kbd{C-v} and @kbd{M-v} let you move the
        !          3094: whole display up or down a few lines.  @kbd{C-v} (@code{scroll-up}) with an
        !          3095: argument shows you that many more lines at the bottom of the window, moving
        !          3096: the text and point up together as @kbd{C-l} might.  @kbd{C-v} with a
        !          3097: negative argument shows you more lines at the top of the window.
        !          3098: @kbd{Meta-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the
        !          3099: opposite direction.@refill
        !          3100: 
        !          3101: @vindex next-screen-context-lines
        !          3102:   To read the buffer a windowful at a time, use @kbd{C-v} with no argument.
        !          3103: It takes the last two lines at the bottom of the window and puts them at
        !          3104: the top, followed by nearly a whole windowful of lines not previously
        !          3105: visible.  If point was in the text scrolled off the top, it moves to the
        !          3106: new top of the window.  @kbd{M-v} with no argument moves backward with
        !          3107: overlap similarly.  The number of lines of overlap across a @kbd{C-v} or
        !          3108: @kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by
        !          3109: default, it is two.
        !          3110: 
        !          3111: @vindex scroll-step
        !          3112:   Scrolling happens automatically if point has moved out of the visible
        !          3113: portion of the text when it is time to display.  Usually the scrolling is
        !          3114: done so as to put point vertically centered within the window.  However, if
        !          3115: the variable @code{scroll-step} has a nonzero value, an attempt is made to
        !          3116: scroll the buffer by that many lines; if that is enough to bring point back
        !          3117: into visibility, that is what is done.
        !          3118: 
        !          3119: @kindex C-x <
        !          3120: @kindex C-x >
        !          3121: @findex scroll-left
        !          3122: @findex scroll-right
        !          3123: @cindex horizontal scrolling
        !          3124:   The text in a window can also be scrolled horizontally.  This means that
        !          3125: each line of text is shifted sideways in the window, and one or more
        !          3126: characters at the beginning of each line are not displayed at all.  When a
        !          3127: window has been scrolled horizontally in this way, text lines are truncated
        !          3128: rather than continued (@pxref{Continuation Lines}), with a @samp{$} appearing
        !          3129: in the first column when there is text truncated to the left, and in the
        !          3130: last column when there is text truncated to the right.
        !          3131: 
        !          3132:   The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected window
        !          3133: to the left by @var{n} columns with argument @var{n}.  With no argument, it scrolls
        !          3134: by almost the full width of the window (two columns less, to be precise).
        !          3135: @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.
        !          3136: The window cannot be scrolled any farther to the right once it is
        !          3137: displaying normally (with each line starting at the window's left margin);
        !          3138: attempting to do so has no effect.
        !          3139: 
        !          3140: @kindex M-r
        !          3141: @findex move-to-window-line
        !          3142:   The commands described above all change the position of point on the
        !          3143: screen, carrying the text with it.  Another command moves point the same
        !          3144: way but leaves the text fixed.  It is @kbd{Meta-r} (@code{move-to-window-line}).
        !          3145: With no argument, it puts point at the beginning of the line at the center
        !          3146: of the window.  An argument is used to specify the line to put point on,
        !          3147: counting from the top if the argument is positive, or from the bottom if it
        !          3148: is negative.  Thus, @kbd{M-0 M-r} moves point to the text at the top of the
        !          3149: window.  @kbd{Meta-r} never causes any text to move on the screen; it
        !          3150: causes point to move with respect to the screen and the text.
        !          3151: 
        !          3152: @menu
        !          3153: * Selective Display::  Hiding lines with lots of indentation.
        !          3154: * Display Vars::       Information on variables for customizing display.
        !          3155: @end menu
        !          3156: 
        !          3157: @node Selective Display, Display Vars, Display, Display
        !          3158: @section Selective Display
        !          3159: @findex set-selective-display
        !          3160: @kindex C-x $
        !          3161: 
        !          3162:   Emacs has the ability to hide lines indented more than a certain number
        !          3163: of columns (you specify how many columns).  You can use this to get an
        !          3164: overview of a part of a program.
        !          3165: 
        !          3166:   To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
        !          3167: numeric argument @var{n}.  (@xref{Arguments}, for how to give the
        !          3168: argument.)  Then lines with at least @var{n} columns of indentation
        !          3169: disappear from the screen.  The only indication of their presence is that
        !          3170: three dots (@samp{@dots{}}) appear at the end of each visible line that is
        !          3171: followed by one or more invisible ones.@refill
        !          3172: 
        !          3173:   The invisible lines are still present in the buffer, and most editing
        !          3174: commands see them as usual, so it is very easy to put point in the middle
        !          3175: of invisible text.  When this happens, the cursor appears at the end of the
        !          3176: previous line, after the three dots.  If point is at the end of the visible
        !          3177: line, before the newline that ends it, the cursor appears before the three
        !          3178: dots.
        !          3179: 
        !          3180:   The commands @kbd{C-n} and @kbd{C-p} move across the invisible lines as if they
        !          3181: were not there.
        !          3182: 
        !          3183:   To make everything visible again, type @kbd{C-x $} with no argument.
        !          3184: 
        !          3185: @node Display Vars,, Selective Display, Display
        !          3186: @section Variables Controlling Display
        !          3187:  
        !          3188:   This section contains information for customization only.  Beginning
        !          3189: users should skip it.
        !          3190: 
        !          3191: @vindex mode-line-inverse-video
        !          3192:   The variable @code{mode-line-inverse-video} controls whether the mode
        !          3193: line is displayed in inverse video (assuming the terminal supports it);
        !          3194: @code{nil} means don't do so.  @xref{Mode Line}.
        !          3195: 
        !          3196: @vindex inverse-video
        !          3197:   If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
        !          3198: to invert all the lines of the display from what they normally are.
        !          3199: 
        !          3200: @vindex visible-bell
        !          3201: If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
        !          3202: to make the whole screen blink when it would normally make an audible bell
        !          3203: sound.  This variable has no effect if your terminal does not have a way
        !          3204: to make the screen blink.@refill
        !          3205: 
        !          3206: @vindex echo-keystrokes
        !          3207: The variable @code{echo-keystrokes} controls the echoing of multi-character
        !          3208: keys; its value is the number of seconds of pause required to cause echoing
        !          3209: to start, or zero meaning don't echo at all.  @xref{Echo Area}.
        !          3210: 
        !          3211: @vindex ctl-arrow
        !          3212: @vindex default-ctl-arrow
        !          3213: If the variable @code{ctl-arrow} is @code{nil}, control characters in the buffer
        !          3214: are displayed with octal escape sequences, all except newline and tab.
        !          3215: This variable has a separate value in each buffer; in new buffers, its
        !          3216: value is initialized from the variable @code{default-ctl-arrow}.
        !          3217: 
        !          3218: @vindex tab-width
        !          3219: @vindex default-tab-width
        !          3220:   Normally, a tab character in the buffer is displayed as whitespace which
        !          3221: extends to the next display tab stop position, and display tab stops come
        !          3222: at intervals equal to eight spaces.  The number of spaces per tab is
        !          3223: controlled by the variable @code{tab-width}, which is local to every
        !          3224: buffer just like @code{ctl-arrow} and gets its value in a new buffer from
        !          3225: @code{default-tab-width}.  Note that how the tab character in the buffer is
        !          3226: displayed has nothing to do with the definition of @key{TAB} as a command.
        !          3227: 
        !          3228: @node Search, Fixit, Display, Top
        !          3229: @chapter Searching and Replacement
        !          3230: @cindex searching
        !          3231: 
        !          3232:   Like other editors, Emacs has commands for searching for occurrences of
        !          3233: a string.  The principal search command is unusual in that it is
        !          3234: @dfn{incremental}; it begins to search before you have finished typing the
        !          3235: search string.  There are also nonincremental search commands more like
        !          3236: those of other editors.
        !          3237: 
        !          3238:   Besides the usual @code{replace-string} command that finds all
        !          3239: occurrences of one string and replaces them with another, Emacs has a fancy
        !          3240: replacement command called @code{query-replace} which asks interactively
        !          3241: which occurrences to replace.
        !          3242: 
        !          3243: @menu
        !          3244: * Incremental Search::     Search happens as you type the string.
        !          3245: * Nonincremental Search::  Specify entire string and then search.
        !          3246: * Word Search::            Search for sequence of words.
        !          3247: * Regexp Search::          Search for match for a regexp.
        !          3248: * Regexps::                Syntax of regular expressions.
        !          3249: * Search Case::            To ignore case while searching, or not.
        !          3250: * Replace::                Search, and replace some or all matches.
        !          3251: * Other Repeating Search:: Operating on all matches for some regexp.
        !          3252: @end menu
        !          3253: 
        !          3254: @node Incremental Search, Nonincremental Search, Search, Search
        !          3255: @section Incremental Search
        !          3256: 
        !          3257:   An incremental search begins searching as soon as you type the first
        !          3258: character of the search string.  As you type in the search string, Emacs
        !          3259: shows you where the string (as you have typed it so far) would be found.
        !          3260: When you have typed enough characters to identify the place you want, you
        !          3261: can stop.  Depending on what you will do next, you may or may not need to
        !          3262: terminate the search explicitly with an @key{ESC} first.
        !          3263: 
        !          3264: @c WideCommands
        !          3265: @table @kbd
        !          3266: @item C-s
        !          3267: Incremental search forward (@code{isearch-forward}).
        !          3268: @item C-r
        !          3269: Incremental search backward (@code{isearch-backward}).
        !          3270: @end table
        !          3271: 
        !          3272: @kindex C-s
        !          3273: @kindex C-r
        !          3274: @findex isearch-forward
        !          3275: @findex isearch-backward
        !          3276:   @kbd{C-s} starts an incremental search.  @kbd{C-s} reads characters from
        !          3277: the keyboard and positions the cursor at the first occurrence of the
        !          3278: characters that you have typed.  If you type @kbd{C-s} and then @kbd{F},
        !          3279: the cursor moves right after the first @samp{F}.  Type an @kbd{O}, and see
        !          3280: the cursor move to after the first @samp{FO}.  After another @kbd{O}, the
        !          3281: cursor is after the first @samp{FOO} after the place where you started the
        !          3282: search.  Meanwhile, the search string @samp{FOO} has been echoed in the
        !          3283: echo area.@refill
        !          3284: 
        !          3285:   The echo area display ends with three dots when actual searching is going
        !          3286: on.  When search is waiting for more input, the three dots are removed.
        !          3287: (On slow terminals, the three dots are not displayed.)
        !          3288: 
        !          3289:   If you make a mistake in typing the search string, you can erase
        !          3290: characters with @key{DEL}.  Each @key{DEL} cancels the last character of
        !          3291: search string.  This does not happen until Emacs is ready to read another
        !          3292: input character; first it must either find, or fail to find, the character
        !          3293: you want to erase.  If you do not want to wait for this to happen, use
        !          3294: @kbd{C-g} as described below.@refill
        !          3295: 
        !          3296:   When you are satisfied with the place you have reached, you can type
        !          3297: @key{ESC}, which stops searching, leaving the cursor where the search
        !          3298: brought it.  Also, any command not specially meaningful in searches stops
        !          3299: the searching and is then executed.  Thus, typing @kbd{C-a} would exit the
        !          3300: search and then move to the beginning of the line.  @key{ESC} is necessary
        !          3301: only if the next command you want to type is a printing character,
        !          3302: @key{DEL}, @key{ESC}, or another control character that is special within
        !          3303: searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s} or @kbd{C-k}).
        !          3304: 
        !          3305:   Sometimes you search for @samp{FOO} and find it, but not the one you
        !          3306: expected to find.  There was a second @samp{FOO} that you forgot about,
        !          3307: before the one you were looking for.  In this event, type another @kbd{C-s}
        !          3308: to move to the next occurrence of the search string.  This can be done any
        !          3309: number of times.  If you overshoot, you can cancel some @kbd{C-s}
        !          3310: characters with @key{DEL}.
        !          3311: 
        !          3312:   After you exit a search, you can search for the same string again by
        !          3313: typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
        !          3314: incremental search, and the second @kbd{C-s} means ``search again''.
        !          3315: 
        !          3316:   If your string is not found at all, the echo area says @samp{Failing
        !          3317: I-Search}.  The cursor is after the place where Emacs found as much of your
        !          3318: string as it could.  Thus, if you search for @samp{FOOT}, and there is no
        !          3319: @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
        !          3320: At this point there are several things you can do.  If your string was
        !          3321: mistyped, you can rub some of it out and correct it.  If you like the place
        !          3322: you have found, you can type @key{ESC} or some other Emacs command to
        !          3323: ``accept what the search offered''.  Or you can type @kbd{C-g}, which
        !          3324: removes from the search string the characters that could not be found (the
        !          3325: @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
        !          3326: @samp{FOOT}).  A second @kbd{C-g} at that point cancels the search
        !          3327: entirely, returning point to where it was when the search started.
        !          3328: 
        !          3329: @cindex quitting (in search)
        !          3330:   The @kbd{C-g} ``quit'' character does special things during searches;
        !          3331: just what it does depends on the status of the search.  If the search has
        !          3332: found what you specified and is waiting for input, @kbd{C-g} cancels the
        !          3333: entire search.  The cursor moves back to where you started the search.  If
        !          3334: @kbd{C-g} is typed when there are characters in the search string that have
        !          3335: not been found---because Emacs is still searching for them, or because it
        !          3336: has failed to find them---then the search string characters which have not
        !          3337: been found are discarded from the search string.  With them gone, the
        !          3338: search is now successful and waiting for more input, so a second @kbd{C-g}
        !          3339: will cancel the entire search.
        !          3340: 
        !          3341:   To search for a control character such as @kbd{C-s} or @key{DEL} or @key{ESC},
        !          3342: you must quote it by typing @kbd{C-q} first.  This function of @kbd{C-q} is
        !          3343: analogous to its meaning as an Emacs command: it causes the following
        !          3344: character to be treated the way a graphic character would normally be
        !          3345: treated in the same context.
        !          3346: 
        !          3347:   You can change to searching backwards with @kbd{C-r}.  If a search fails
        !          3348: because the place you started was too late in the file, you should do this.
        !          3349: Repeated @kbd{C-r} keeps looking for more occurrences backwards.  A
        !          3350: @kbd{C-s} starts going forwards again.  @kbd{C-r} in a search can be cancelled
        !          3351: with @key{DEL}.
        !          3352: 
        !          3353:   If you know initially that you want to search backwards, you can
        !          3354: use @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r}
        !          3355: is also a key running a command (@code{isearch-reverse}) to search
        !          3356: backward.
        !          3357: 
        !          3358:   The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search
        !          3359: to grab text from the buffer into the search string.  This makes it
        !          3360: convenient to search for another occurrence of text at point.  @kbd{C-w}
        !          3361: copies the word after point as part of the search string, advancing
        !          3362: point over that word.  Another @kbd{C-s} to repeat the search will then
        !          3363: search for a string including that word.  @kbd{C-y} is similar to @kbd{C-w}
        !          3364: but copies all the rest of the current line into the search string.
        !          3365: 
        !          3366:   All the characters special in incremental search can be changed by setting
        !          3367: the following variables:
        !          3368: 
        !          3369: @vindex search-delete-char
        !          3370: @vindex search-exit-char
        !          3371: @vindex search-quote-char
        !          3372: @vindex search-repeat-char
        !          3373: @vindex search-reverse-char
        !          3374: @vindex search-yank-line-char
        !          3375: @vindex search-yank-word-char
        !          3376: @table @code
        !          3377: @item search-delete-char
        !          3378: Character to delete from incremental search string (normally @key{DEL}).
        !          3379: @item search-exit-char
        !          3380: Character to exit incremental search (normally @key{ESC}).
        !          3381: @item search-quote-char
        !          3382: Character to quote special characters for incremental search (normally
        !          3383: @kbd{C-q}).
        !          3384: @item search-repeat-char
        !          3385: Character to repeat incremental search forwards (normally @kbd{C-s}).
        !          3386: @item search-reverse-char
        !          3387: Character to repeat incremental search backwards (normally @kbd{C-r}).
        !          3388: @item search-yank-line-char
        !          3389: Character to pull rest of line from buffer into search string
        !          3390: (normally @kbd{C-y}).
        !          3391: @item search-yank-word-char
        !          3392: Character to pull next word from buffer into search string (normally
        !          3393: @kbd{C-w}).
        !          3394: @end table
        !          3395: 
        !          3396: @subsection Slow Terminal Incremental Search
        !          3397: 
        !          3398:   Incremental search on a slow terminal uses a modified style of display
        !          3399: that is designed to take less time.  Instead of redisplaying the buffer at
        !          3400: each place the search gets to, it creates a new single-line window and uses
        !          3401: that to display the line that the search has found.  The single-line window
        !          3402: comes into play as soon as point gets outside of the text that is already
        !          3403: on the screen.
        !          3404: 
        !          3405:   When the search is terminated, the single-line window is removed.  Only
        !          3406: at this time is the window in which the search was done redisplayed to show
        !          3407: its new value of point.
        !          3408: 
        !          3409:   The three dots at the end of the search string, normally used to indicate
        !          3410: that searching is going on, are not displayed in slow style display.
        !          3411: 
        !          3412: @vindex isearch-slow-speed
        !          3413:   The slow terminal style of display is used when the terminal baud rate is
        !          3414: less than or equal to the value of the variable @code{isearch-slow-speed},
        !          3415: initially 1200.
        !          3416: 
        !          3417: @node Nonincremental Search, Word Search, Incremental Search, Search
        !          3418: @section Nonincremental Search
        !          3419: @cindex nonincremental search
        !          3420: 
        !          3421:   Emacs also has conventional nonincremental search commands, which require
        !          3422: you to type the entire search string before searching begins.
        !          3423: 
        !          3424: @table @kbd
        !          3425: @item C-s @key{ESC} @var{string} @key{RET}
        !          3426: Search for @var{string}.
        !          3427: @item C-r @key{ESC} @var{string} @key{RET}
        !          3428: Search backward for @var{string}.
        !          3429: @end table
        !          3430: 
        !          3431:   To do a nonincremental search, first type @kbd{C-s @key{ESC}}.  This
        !          3432: enters the minibuffer to read the search string; terminate the string with
        !          3433: @key{RET}, and then the search is done.  If the string is not found the
        !          3434: search command gets an error.
        !          3435: 
        !          3436:   The way @kbd{C-s @key{ESC}} works is that the @kbd{C-s} invokes
        !          3437: incremental search, which is specially programmed to invoke nonincremental
        !          3438: search if the argument you give it is empty.  (Such an empty argument would
        !          3439: otherwise be useless.)  @kbd{C-r @key{ESC}} also works this way.
        !          3440: 
        !          3441: @findex search-forward
        !          3442: @findex search-backward
        !          3443:   Forward and backward nonincremental searches are implemented by the
        !          3444: commands @code{search-forward} and @code{search-backward}.  These commands
        !          3445: may be bound to keys in the usual manner.  The reason that they are reached
        !          3446: by special-case code in incremental search is because @kbd{C-s @key{ESC}}
        !          3447: is the traditional sequence of characters used in Emacs to invoke
        !          3448: nonincremental search.
        !          3449: 
        !          3450:   However, nonincremental searches performed using @kbd{C-s @key{ESC}} do
        !          3451: not call @code{search-forward} right away.  The first thing done is to see
        !          3452: if the next character is @kbd{C-w}, which requests a word search.
        !          3453: @ifinfo
        !          3454: @xref{Word Search}.
        !          3455: @end ifinfo
        !          3456: 
        !          3457: @node Word Search, Regexp Search, Nonincremental Search, Search
        !          3458: @section Word Search
        !          3459: @cindex word search
        !          3460: 
        !          3461:   Word search searches for a sequence of words without regard to how the
        !          3462: words are separated.  More precisely, you type a string of many words,
        !          3463: using single spaces to separate them, and the string can be found even if
        !          3464: there are multiple spaces, newlines or other punctuation between the words.
        !          3465: 
        !          3466:   Word search is useful in editing documents formatted by text formatters.
        !          3467: If you edit while looking at the printed, formatted version, you can't tell
        !          3468: where the line breaks are in the source file.  With word search, you can
        !          3469: search without having to know them.
        !          3470: 
        !          3471: @table @kbd
        !          3472: @item C-s @key{ESC} C-w @var{words} @key{RET}
        !          3473: Search for @var{words}, ignoring differences in punctuation.
        !          3474: @item C-r @key{ESC} C-w @var{words} @key{RET}
        !          3475: Search backward for @var{words}, ignoring differences in punctuation.
        !          3476: @end table
        !          3477: 
        !          3478:   Word search is a special case of nonincremental search and is invoked
        !          3479: with @kbd{C-s @key{ESC} C-w}.  This is followed by the search string, which
        !          3480: must always be terminated with @key{RET}.  Being nonincremental, this
        !          3481: search does not start until the argument is terminated.  It works by
        !          3482: constructing a regular expression and searching for that.  @xref{Regexp
        !          3483: Search}.
        !          3484: 
        !          3485:   A backward word search can be done by @kbd{C-r @key{ESC} C-w}.
        !          3486: 
        !          3487: @findex word-search-forward
        !          3488: @findex word-search-backward
        !          3489:   Forward and backward word searches are implemented by the commands
        !          3490: @code{word-search-forward} and @code{word-search-backward}.  These commands
        !          3491: may be bound to keys in the usual manner.  The reason that they are reached
        !          3492: by special-case code in incremental and nonincremental search is because
        !          3493: @kbd{C-s @key{ESC} C-w} is the traditional Emacs sequence of keys to use to
        !          3494: do a word search.
        !          3495: 
        !          3496: @node Regexp Search, Regexps, Word Search, Search
        !          3497: @section Regular Expression Search
        !          3498: @cindex regular expression
        !          3499: @cindex regexp
        !          3500: 
        !          3501:   A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
        !          3502: denotes a set of strings, possibly an infinite set.  Searching for matches
        !          3503: for a regexp is a very powerful operation that editors on Unix systems have
        !          3504: traditionally offered.  In GNU Emacs, you can search for the next match for
        !          3505: a regexp either incrementally or not.
        !          3506: 
        !          3507: @kindex C-M-s
        !          3508: @findex isearch-forward-regexp
        !          3509:   Incremental search for a regexp is done by typing @kbd{C-M-s}
        !          3510: (@code{isearch-forward-regexp}).  This command reads a search string
        !          3511: incrementally just like @kbd{C-s}, but it treats the search string as a
        !          3512: regexp rather than looking for an exact match against the text in the
        !          3513: buffer.  Each time you add text to the search string, you make the regexp
        !          3514: longer, and the new regexp is searched for.
        !          3515: 
        !          3516:   Note that adding characters to the regexp in an incremental regexp search
        !          3517: does not make the cursor move back and start again.  Perhaps it ought to; I
        !          3518: am not sure.  As it stands, if you have searched for @samp{foo} and you
        !          3519: add @samp{\|bar}, the search will not check for a @samp{bar} in the
        !          3520: buffer before the @samp{foo}.
        !          3521: 
        !          3522: @findex re-search-forward
        !          3523: @findex re-search-backward
        !          3524:   Nonincremental search for a regexp is done by the functions
        !          3525: @code{re-search-forward} and @code{re-search-backward}.  You can invoke
        !          3526: these with @kbd{M-x}, or bind them to keys.  Also, you can call
        !          3527: @code{re-search-forward} by way of incremental regexp search with
        !          3528: @kbd{C-M-s @key{ESC}}.
        !          3529: 
        !          3530: @node Regexps, Search Case, Regexp Search, Search
        !          3531: @section Syntax of Regular Expressions
        !          3532: 
        !          3533: Regular expressions have a syntax in which a few characters are special
        !          3534: constructs and the rest are @dfn{ordinary}.  An ordinary character is a
        !          3535: simple regular expression which matches that character and nothing else.
        !          3536: The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
        !          3537: @samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}.  Any other character
        !          3538: appearing in a regular expression is ordinary, unless a @samp{\} precedes
        !          3539: it.@refill
        !          3540: 
        !          3541: No new special characters will ever be defined.  All extensions to the
        !          3542: regular expression syntax are made by defining new two-character
        !          3543: constructs that begin with @samp{\}.
        !          3544: 
        !          3545: For example, @samp{f} is not a special character, so it is ordinary, and
        !          3546: therefore @samp{f} is a regular expression that matches the string @samp{f}
        !          3547: and no other string.  (It does @i{not} match the string @samp{ff}.)  Likewise,
        !          3548: @samp{o} is a regular expression that matches only @samp{o}.@refill
        !          3549: 
        !          3550: Any two regular expressions @var{a} and @var{b} can be concatenated.  The
        !          3551: result is a regular expression which matches a string if @var{a} matches
        !          3552: some amount of the beginning of that string and @var{b} matches the rest of
        !          3553: the string.@refill
        !          3554: 
        !          3555: As a simple example, we can concatenate the regular expressions @samp{f}
        !          3556: and @samp{o} to get the regular expression @samp{fo}, which matches only
        !          3557: the string @samp{fo}.  Still trivial.  To do something nontrivial, you
        !          3558: need to use one of the special characters.  Here is a list of them.
        !          3559: 
        !          3560: @table @kbd
        !          3561: @item .
        !          3562: is a special character that matches anything except a newline.  Using
        !          3563: concatenation, we can make regular expressions like @samp{a.b} which
        !          3564: matches any three-character string which begins with @samp{a} and ends
        !          3565: with @samp{b}.@refill
        !          3566: 
        !          3567: @item *
        !          3568: is not a construct by itself; it is a suffix, which means the
        !          3569: preceding regular expression is to be repeated as many times as
        !          3570: possible.  In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
        !          3571: @samp{fo*} matches @samp{f} followed by any number of @samp{o}s.  The
        !          3572: case of zero @samp{o}s is allowed: @samp{fo*} does match @samp{f}.@refill
        !          3573: 
        !          3574: @samp{*} always applies to the @i{smallest} possible preceding expression.
        !          3575: Thus, @samp{fo*} has a repeating @samp{o}, not a repeating @samp{fo}.@refill
        !          3576: 
        !          3577: The matcher processes a @samp{*} construct by matching, immediately,
        !          3578: as many repetitions as can be found.  Then it continues with the rest
        !          3579: of the pattern.  If that fails, backtracking occurs, discarding some
        !          3580: of the matches of the @samp{*}-modified construct in case that makes
        !          3581: it possible to match the rest of the pattern.  For example, matching
        !          3582: @samp{c[ad]*ar} against the string @samp{caddaar}, the @samp{[ad]*}
        !          3583: first matches @samp{addaa}, but this does not allow the next @samp{a}
        !          3584: in the pattern to match.  So the last of the matches of @samp{[ad]} is
        !          3585: undone and the following @samp{a} is tried again.  Now it
        !          3586: succeeds.@refill
        !          3587: 
        !          3588: @item +
        !          3589: Is a suffix character similar to @samp{*} except that it requires that
        !          3590: the preceding expression be matched at least once.  So, for example,
        !          3591: @samp{c[ad]+r} will match the strings @samp{car} and @samp{caaadar}
        !          3592: but not the string @samp{cr}, whereas @samp{c[ad]*r} would match all
        !          3593: three strings.@refill
        !          3594: 
        !          3595: @item ?
        !          3596: Is a suffix character similar to @samp{*} except that it can match the
        !          3597: preceding expression either once or not at all.  For example,
        !          3598: @samp{c[ad]?r} will match @samp{car}, @samp{cdr} or @samp{cr}; nothing else.
        !          3599: 
        !          3600: @item [ ... ]
        !          3601: @samp{[} begins a @dfn{character set}, which is terminated by a
        !          3602: @samp{]}.  In the simplest case, the characters between the two form
        !          3603: the set.  Thus, @samp{[ad]} matches either @samp{a} or @samp{d}, and
        !          3604: @samp{[ad]*} matches any string of @samp{a} and @samp{d} (including
        !          3605: the empty string), from which it follows that @samp{c[ad]*r} matches
        !          3606: @samp{car}, etc.@refill
        !          3607: 
        !          3608: Character ranges can also be included in a character set, by writing
        !          3609: two characters with a @samp{-} between them.  Thus, @samp{[a-z]}
        !          3610: matches any lower-case letter.  Ranges may be intermixed freely with
        !          3611: individual characters, as in @samp{[a-z$%.]}, which matches any lower
        !          3612: case letter or @samp{$}, @samp{%} or period.@refill
        !          3613: 
        !          3614: Note that the usual special characters are not special any more inside
        !          3615: a character set.  A completely different set of special characters
        !          3616: exists inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
        !          3617: 
        !          3618: To include a @samp{]} in a character set, you must make it the first
        !          3619: character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To
        !          3620: include a @samp{-}, write @samp{---}, which is a range containing only
        !          3621: @samp{-}.  To include @samp{^}, make it other than the first character
        !          3622: in the set.@refill
        !          3623: 
        !          3624: @item [^ ... ]
        !          3625: @samp{[^} begins a @dfn{complement character set}, which matches any
        !          3626: character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]}
        !          3627: matches all characters @i{except} letters and digits.@refill
        !          3628: 
        !          3629: @samp{^} is not special in a character set unless it is the first
        !          3630: character.  The character following the @samp{^} is treated as if it
        !          3631: were first (it may be a @samp{-} or a @samp{]}).
        !          3632: 
        !          3633: Note that a complement character set can match a newline, unless
        !          3634: newline is mentioned as one of the characters not to match.
        !          3635: 
        !          3636: @item ^
        !          3637: is a special character that matches the empty string, but only if at
        !          3638: the beginning of a line in the text being matched.  Otherwise it fails
        !          3639: to match anything.  Thus, @samp{^foo} matches a @samp{foo} which occurs
        !          3640: at the beginning of a line.
        !          3641: 
        !          3642: @item $
        !          3643: is similar to @samp{^} but matches only at the end of a line.  Thus,
        !          3644: @samp{xx*$} matches a string of one @samp{x} or more at the end of a line.
        !          3645: 
        !          3646: @item \
        !          3647: has two functions: it quotes the special characters (including
        !          3648: @samp{\}), and it introduces additional special constructs.
        !          3649: 
        !          3650: Because @samp{\} quotes special characters, @samp{\$} is a regular
        !          3651: expression which matches only @samp{$}, and @samp{\[} is a regular
        !          3652: expression which matches only @samp{[}, and so on.@refill
        !          3653: @end table
        !          3654: 
        !          3655: Note: for historical compatibility, special characters are treated as
        !          3656: ordinary ones if they are in contexts where their special meanings make no
        !          3657: sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
        !          3658: no preceding expression on which the @samp{*} can act.  It is poor practice
        !          3659: to depend on this behavior; better to quote the special character anyway,
        !          3660: regardless of where is appears.@refill
        !          3661: 
        !          3662: For the most part, @samp{\} followed by any character matches only
        !          3663: that character.  However, there are several exceptions: characters
        !          3664: which, when preceded by @samp{\}, are special constructs.  Such
        !          3665: characters are always ordinary when encountered on their own.
        !          3666: 
        !          3667: @table @kbd
        !          3668: @item \|
        !          3669: specifies an alternative.
        !          3670: Two regular expressions @var{a} and @var{b} with @samp{\|} in
        !          3671: between form an expression that matches anything that either @var{a} or
        !          3672: @var{b} will match.@refill
        !          3673: 
        !          3674: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
        !          3675: but no other string.@refill
        !          3676: 
        !          3677: @samp{\|} applies to the largest possible surrounding expressions.  Only a
        !          3678: surrounding @samp{\( ... \)} grouping can limit the grouping power of
        !          3679: @samp{\|}.@refill
        !          3680: 
        !          3681: Full backtracking capability exists to handle multiple uses of @samp{\|}.
        !          3682: 
        !          3683: @item \( ... \)
        !          3684: is a grouping construct that serves three purposes:
        !          3685: 
        !          3686: @enumerate
        !          3687: @item
        !          3688: To enclose a set of @samp{\|} alternatives for other operations.
        !          3689: Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
        !          3690: 
        !          3691: @item
        !          3692: To enclose a complicated expression for the postfix @samp{*} to operate on.
        !          3693: Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any (zero or
        !          3694: more) number of @samp{na} strings.@refill
        !          3695: 
        !          3696: @item
        !          3697: To mark a matched substring for future reference.
        !          3698: 
        !          3699: @end enumerate
        !          3700: 
        !          3701: This last application is not a consequence of the idea of a
        !          3702: parenthetical grouping; it is a separate feature which happens to be
        !          3703: assigned as a second meaning to the same @samp{\( ... \)} construct
        !          3704: because there is no conflict in practice between the two meanings.
        !          3705: Here is an explanation of this feature:
        !          3706: 
        !          3707: @item \@var{digit}
        !          3708: after the end of a @samp{\( ... \)} construct, the matcher remembers the
        !          3709: beginning and end of the text matched by that construct.  Then, later on
        !          3710: in the regular expression, you can use @samp{\} followed by @var{digit}
        !          3711: to mean ``match the same text matched the @var{digit}'th time by the
        !          3712: @samp{\( ... \)} construct.''@refill
        !          3713: 
        !          3714: The strings matching the first nine @samp{\( ... \)} constructs
        !          3715: appearing in a regular expression are assigned numbers 1 through 9 in
        !          3716: order of their beginnings.  @samp{\1} through @samp{\9} may be used to
        !          3717: refer to the text matched by the corresponding @samp{\( ... \)}
        !          3718: construct.
        !          3719: 
        !          3720: For example, @samp{\(.*\)\1} matches any newline-free string that is
        !          3721: composed of two identical halves.  The @samp{\(.*\)} matches the first
        !          3722: half, which may be anything, but the @samp{\1} that follows must match
        !          3723: the same exact text.
        !          3724: 
        !          3725: @item \`
        !          3726: matches the empty string, but only if it is at the beginning
        !          3727: of the buffer.
        !          3728: 
        !          3729: @item \'
        !          3730: matches the empty string, but only if it is at the end of
        !          3731: the buffer.
        !          3732: 
        !          3733: @item \b
        !          3734: matches the empty string, but only if it is at the beginning or
        !          3735: end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
        !          3736: @samp{foo} as a separate word.  @samp{\bballs?\b} matches
        !          3737: @samp{ball} or @samp{balls} as a separate word.@refill
        !          3738: 
        !          3739: @item \B
        !          3740: matches the empty string, provided it is @i{not} at the beginning or
        !          3741: end of a word.
        !          3742: 
        !          3743: @item \<
        !          3744: matches the empty string, provided it is at the beginning of a word.
        !          3745: 
        !          3746: @item \>
        !          3747: matches the empty string, provided it is at the end of a word.
        !          3748: 
        !          3749: @item \w
        !          3750: matches any word-constituent character.  The editor syntax table
        !          3751: determines which characters these are.
        !          3752: 
        !          3753: @item \W
        !          3754: matches any character that is not a word-constituent.
        !          3755: 
        !          3756: @item \s@var{code}
        !          3757: matches any character whose syntax is @var{code}.  @var{code} is a
        !          3758: character which represents a syntax code: thus, @samp{w} for word
        !          3759: constituent, @samp{-} for whitespace, @samp{(} for open-parenthesis,
        !          3760: etc.  @xref{Syntax}.@refill
        !          3761: 
        !          3762: @item \S@var{code}
        !          3763: matches any character whose syntax is not @var{code}.
        !          3764: @end table
        !          3765: 
        !          3766: @node Search Case, Replace, Regexps, Search
        !          3767: @section Searching and Case
        !          3768: 
        !          3769: @vindex case-fold-search
        !          3770: @vindex default-case-fold-search
        !          3771:   All sorts of searches in Emacs normally ignore the case of the text they
        !          3772: are searching through; if you specify searching for @samp{FOO}, then
        !          3773: @samp{Foo} and @samp{foo} are also considered a match.  Regexps, and in
        !          3774: particular character sets, are included: @samp{[aB]} would match @samp{a}
        !          3775: or @samp{A} or @samp{b} or @samp{B}.@refill
        !          3776: 
        !          3777:   If you do not want this feature, set the variable @code{case-fold-search}
        !          3778: to @code{nil}.  Then all letters must match exactly, including case.  This
        !          3779: variable has separate values in all individual buffers; in a new buffer,
        !          3780: its value is initialized from @code{default-case-fold-search}.
        !          3781: @xref{Variables}.
        !          3782: 
        !          3783: @node Replace, Other Repeating Search, Search Case, Search
        !          3784: @section Replacement Commands
        !          3785: @cindex replacement
        !          3786: @cindex string substitution
        !          3787: @cindex global substitution
        !          3788: 
        !          3789:   Global search-and-replace operations are not needed as often in Emacs as
        !          3790: they are in other editors, but they are available.  In addition to the
        !          3791: simple @code{replace-string} command which is like that found in most
        !          3792: editors, there is a @code{query-replace} command which asks you, for each
        !          3793: occurrence of the pattern, whether to replace it.
        !          3794: 
        !          3795:   The replace commands all replace one string (or regexp) with one
        !          3796: replacement string.  It is possible to perform several replacements in
        !          3797: parallel using the command @code{expand-region-abbrevs}.  @xref{Expanding
        !          3798: Abbrevs}.
        !          3799: 
        !          3800: @menu
        !          3801: * Unconditional Replace::  Everything about replacement except for querying.
        !          3802: * Query Replace::          How to use querying.
        !          3803: @end menu
        !          3804: 
        !          3805: @node Unconditional Replace, Query Replace, Replace, Replace
        !          3806: @subsection Unconditional Replacement
        !          3807: @findex replace-string
        !          3808: @findex replace-regexp
        !          3809: 
        !          3810: @table @kbd
        !          3811: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
        !          3812: Replace every occurrence of @var{string} with @var{newstring}.
        !          3813: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
        !          3814: Replace every match for @var{regexp} with @var{newstring}.
        !          3815: @end table
        !          3816: 
        !          3817:   To replace every instance of @samp{foo} after point with @samp{bar}, use
        !          3818: the command @kbd{M-x replace-string} with the two arguments @samp{foo} and
        !          3819: @samp{bar}.  Replacement occurs only after point, so if you want to cover
        !          3820: the whole buffer you must go to the beginning first.  All occurrences up to
        !          3821: the end of the buffer are replaced; to limit replacement to part of the
        !          3822: buffer, narrow to that part of the buffer before doing the replacement.
        !          3823: 
        !          3824:   When @code{replace-string} exits, point is left at the last occurrence
        !          3825: replaced.  The value of point when the @code{replace-string} command was
        !          3826: issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back
        !          3827: there.
        !          3828: 
        !          3829:   @code{replace-string} replaces exact matches for a single string.  The
        !          3830: similar command @code{replace-regexp} replaces any match for a specified
        !          3831: pattern.
        !          3832: 
        !          3833:   In @code{replace-regexp}, the @var{newstring} need not be constant.  It
        !          3834: can refer to all or part of what is matched by the @var{regexp}.  @samp{\&}
        !          3835: in @var{newstring} is replaced by the entire text being replaced.
        !          3836: @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, is replaced
        !          3837: by whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
        !          3838: For example,@refill
        !          3839: 
        !          3840: @example
        !          3841: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
        !          3842: @end example
        !          3843: 
        !          3844: @noindent
        !          3845: would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
        !          3846: with @samp{cddr-safe}.
        !          3847: 
        !          3848: @example
        !          3849: M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
        !          3850: @end example
        !          3851: 
        !          3852: @noindent
        !          3853: would perform exactly the opposite replacements.  To include a @samp{\}
        !          3854: in the text to replace with, you must give @samp{\\}.
        !          3855: 
        !          3856:   A numeric argument to either of the @code{replace-} commands restricts
        !          3857: replacement to matches that are surrounded by word boundaries.
        !          3858: 
        !          3859: @vindex case-replace
        !          3860: @vindex case-fold-search
        !          3861:   If the arguments to @code{replace-string} are in lower case, it preserves
        !          3862: case when it makes a replacement.  Thus, the command
        !          3863: 
        !          3864: @example
        !          3865: M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
        !          3866: @end example
        !          3867: 
        !          3868: @noindent
        !          3869: replaces a lower case @samp{foo} with a lower case @samp{bar}, @samp{FOO}
        !          3870: with @samp{BAR}, and @samp{Foo} with @samp{Bar}.  If upper case letters are
        !          3871: used in the second argument, they remain upper case every time that
        !          3872: argument is inserted.  If upper case letters are used in the first
        !          3873: argument, the second argument is always substituted exactly as given, with
        !          3874: no case conversion.  Likewise, if the variable @code{case-replace} is set
        !          3875: to @code{nil}, replacement is done without case conversion.  If
        !          3876: @code{case-fold-search} is set to @code{nil}, case is significant in
        !          3877: matching occurrences of @samp{foo} to replace; also, case conversion of the
        !          3878: replacement string is not done.
        !          3879: 
        !          3880: @node Query Replace,, Unconditional Replace, Replace
        !          3881: @subsection Query Replace
        !          3882: @cindex Query Replace
        !          3883: 
        !          3884: @table @kbd
        !          3885: @item M-% @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
        !          3886: @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
        !          3887: Replace some occurrences of @var{string} with @var{newstring}.
        !          3888: @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
        !          3889: Replace some matches for @var{string} with @var{newstring}.
        !          3890: @end table
        !          3891: 
        !          3892: @kindex M-%
        !          3893: @findex query-replace
        !          3894:   If you want to change only some of the occurrences of @samp{foo} to
        !          3895: @samp{bar}, not all of them, then you cannot use an ordinary
        !          3896: @code{replace-string}.  Instead, use @kbd{M-%} (@code{query-replace}).
        !          3897: This command finds occurrences of @samp{foo} one by one, displays each
        !          3898: occurrence and asks you whether to replace it.  A numeric argument to
        !          3899: @code{query-replace} tells it to consider only occurrences that are bounded
        !          3900: by word-delimiter characters.@refill
        !          3901: 
        !          3902:   Aside from querying, @code{query-replace} works just like
        !          3903: @code{replace-string}, and @code{query-replace-regexp} works
        !          3904: just like @code{replace-regexp}.@refill
        !          3905: 
        !          3906:   The things you can type when you are shown an occurrence of @var{string}
        !          3907: or a match for @var{regexp} are:
        !          3908: 
        !          3909: @kindex SPC (query-replace)
        !          3910: @kindex DEL (query-replace)
        !          3911: @kindex Comma (query-replace)
        !          3912: @kindex ESC (query-replace)
        !          3913: @kindex . (query-replace)
        !          3914: @kindex ! (query-replace)
        !          3915: @kindex ^ (query-replace)
        !          3916: @kindex C-r (query-replace)
        !          3917: @kindex C-w (query-replace)
        !          3918: @kindex C-l (query-replace)
        !          3919: 
        !          3920: @c WideCommands
        !          3921: @table @kbd
        !          3922: @item @key{SPC}
        !          3923: to replace the occurrence with @var{newstring}.  This preserves case, just
        !          3924: like @code{replace-string}, provided @code{case-replace} is non-@code{nil},
        !          3925: as it normally is.@refill
        !          3926: 
        !          3927: @item @key{DEL}
        !          3928: to skip to the next occurrence without replacing this one.
        !          3929: 
        !          3930: @item ,
        !          3931: to replace this occurrence and display the result.  You are then asked
        !          3932: for another input character, except that since the replacement has
        !          3933: already been made, @key{DEL} and @key{SPC} are equivalent.  You could
        !          3934: type @kbd{C-r} at this point (see below) to alter the replaced text.  You
        !          3935: could also type @kbd{C-x u} to undo the replacement; this exits the
        !          3936: @code{query-replace}, so if you want to do further replacement you must use
        !          3937: @kbd{C-x ESC} to restart (@pxref{Repetition}).
        !          3938: 
        !          3939: @item @key{ESC}
        !          3940: to exit without doing any more replacements.
        !          3941: 
        !          3942: @item .
        !          3943: to replace this occurrence and then exit.
        !          3944: 
        !          3945: @item !
        !          3946: to replace all remaining occurrences without asking again.
        !          3947: 
        !          3948: @item ^
        !          3949: to go back to the location of the previous occurrence (or what used to
        !          3950: be an occurrence), in case changed it by mistake.  This works by
        !          3951: popping the mark ring.  Only one @kbd{^} is allowed, because only one
        !          3952: previous replacement location is kept during @code{query-replace}.
        !          3953: 
        !          3954: @item C-r
        !          3955: to enter a recursive editing level, in case the occurrence needs to be
        !          3956: edited rather than just replaced with @var{newstring}.  When you are
        !          3957: done, exit the recursive editing level with @kbd{C-M-c} and the next
        !          3958: occurrence will be displayed.  @xref{Recursive Edit}.
        !          3959: 
        !          3960: @item C-w
        !          3961: to delete the occurrence, and then enter a recursive editing level as
        !          3962: in @kbd{C-r}.  Use the recursive edit to insert text to replace the
        !          3963: deleted occurrence of @var{string}.  When done, exit the recursive
        !          3964: editing level with @kbd{C-M-c} and the next occurrence will be
        !          3965: displayed.
        !          3966: 
        !          3967: @item C-l
        !          3968: to redisplay the screen and then give another answer.
        !          3969: 
        !          3970: @item C-h
        !          3971: to display a message summarizing these options, then give another
        !          3972: answer.
        !          3973: @end table
        !          3974: 
        !          3975:   If you type any other character, the @code{query-replace} is exited, and
        !          3976: the character executed as a command.  To restart the @code{query-replace},
        !          3977: use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it
        !          3978: used the minibuffer to read its arguments.  @xref{Repetition, C-x ESC}.
        !          3979:   
        !          3980: @node Other Repeating Search,, Replace, Search
        !          3981: @section Other Search-and-Loop Commands
        !          3982: 
        !          3983:   Here are some other commands that find matches for a regular expression.
        !          3984: They all operate from point to the end of the buffer.
        !          3985: 
        !          3986: @findex list-matching-lines
        !          3987: @findex count-matches
        !          3988: @findex delete-non-matching-lines
        !          3989: @findex delete-matching-lines
        !          3990: @c grosscommands
        !          3991: @table @kbd
        !          3992: @item M-x list-matching-lines
        !          3993: Print each line that follows point and contains a match for the
        !          3994: specified regexp.  A numeric argument specifies the number of context
        !          3995: lines to print before and after each matching line; the default is
        !          3996: none.
        !          3997: 
        !          3998: @item M-x count-matches
        !          3999: Print the number of matches following point for the specified regexp.
        !          4000: 
        !          4001: @item M-x delete-non-matching-lines
        !          4002: Delete each line that follows point and does not contain a match for
        !          4003: the specified regexp.
        !          4004: 
        !          4005: @item M-x delete-matching-lines
        !          4006: Delete each line that follows point and contains a match for the
        !          4007: specified regexp.
        !          4008: @end table
        !          4009: 
        !          4010: @node Fixit, Files, Search, Top
        !          4011: @chapter Commands for Fixing Typos
        !          4012: @cindex typos
        !          4013: 
        !          4014:   In this chapter we describe the commands that are especially useful for
        !          4015: the times when you catch a mistake in your text just after you have made
        !          4016: it, or change your mind while composing text on line.
        !          4017: 
        !          4018: @menu
        !          4019: * Kill Errors:: Commands to kill a batch of recently entered text.
        !          4020: * Transpose::   Exchanging two characters, words, lines, lists...
        !          4021: * Fixing Case:: Correcting case of last word entered.
        !          4022: * Spelling::    Apply spelling checker to a word, or a whole file.
        !          4023: @end menu
        !          4024: 
        !          4025: @node Kill Errors, Transpose, Fixit, Fixit
        !          4026: @section Killing Your Mistakes
        !          4027: 
        !          4028: @table @kbd
        !          4029: @item @key{DEL}
        !          4030: Delete last character (@code{delete-backward-char}).
        !          4031: @item M-@key{DEL}
        !          4032: Kill last word (@code{backward-kill-word}).
        !          4033: @item C-x @key{DEL}
        !          4034: Kill to beginning of sentence (@code{backward-kill-sentence}).
        !          4035: @end table
        !          4036: 
        !          4037: @kindex DEL
        !          4038: @findex delete-backward-char
        !          4039:   The @key{DEL} character (@code{delete-backward-char}) is the most
        !          4040: important correction command.  When used among graphic (self-inserting)
        !          4041: characters, it can be thought of as canceling the last character typed.
        !          4042: 
        !          4043: @kindex M-DEL
        !          4044: @kindex C-x DEL
        !          4045: @findex backward-kill-word
        !          4046: @findex backward-kill-sentence
        !          4047:   When your mistake is longer than a couple of characters, it might be more
        !          4048: convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}.
        !          4049: @kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x
        !          4050: @key{DEL}} kills back to the start of the last sentence.  @kbd{C-x
        !          4051: @key{DEL}} is particularly useful when you are thinking of what to write as
        !          4052: you type it, in case you change your mind about phrasing.
        !          4053: @kbd{M-@key{DEL}} and @kbd{C-x @key{DEL}} save the killed text for
        !          4054: @kbd{C-y} and @kbd{M-y} to retrieve.  @xref{Yanking}.@refill
        !          4055: 
        !          4056:   @kbd{M-@key{DEL}} is often useful even when you have typed only a few
        !          4057: characters wrong, if you know you are confused in your typing and aren't
        !          4058: sure exactly what you typed.  At such a time, you cannot correct with
        !          4059: @key{DEL} except by looking at the screen to see what you did.  It requires
        !          4060: less thought to kill the whole word and start over again.
        !          4061: 
        !          4062: @node Transpose, Fixing Case, Kill Errors, Fixit
        !          4063: @section Transposing Text
        !          4064: 
        !          4065: @table @kbd
        !          4066: @item C-t
        !          4067: Transpose two characters (@code{transpose-chars}).
        !          4068: @item M-t
        !          4069: Transpose two words (@code{transpose-words}).
        !          4070: @item C-M-t
        !          4071: Transpose two balanced expressions (@code{transpose-sexps}).
        !          4072: @item C-x C-t
        !          4073: Transpose two lines (@code{transpose-lines}).
        !          4074: @end table
        !          4075: 
        !          4076: @cindex transposition
        !          4077: @kindex C-t
        !          4078: @findex transpose-chars
        !          4079:   The common error of transposing two characters can be fixed, when they
        !          4080: are adjacent, with the @kbd{C-t} command (@code{transpose-chars}).  Normally,
        !          4081: @kbd{C-t} transposes the two characters on either side of point.  When
        !          4082: given at the end of a line, rather than transposing the last character of
        !          4083: the line with the newline, which would be useless, @kbd{C-t} transposes the
        !          4084: last two characters on the line.  So, if you catch your transposition error
        !          4085: right away, you can fix it with just a @kbd{C-t}.  If you don't catch it so
        !          4086: fast, you must move the cursor back to between the two transposed
        !          4087: characters.  If you transposed a space with the last character of the word
        !          4088: before it, the word motion commands are a good way of getting there.
        !          4089: Otherwise, a reverse search (@kbd{C-r}) is often the best way.
        !          4090: @xref{Search}.
        !          4091: 
        !          4092: 
        !          4093: @kindex C-x C-t
        !          4094: @findex transpose-lines
        !          4095: @kindex M-t
        !          4096: @findex transpose-words
        !          4097: @kindex C-M-t
        !          4098: @findex transpose-sexps
        !          4099:   @kbd{Meta-t} (@code{transpose-words}) transposes the word before point
        !          4100: with the word after point.  It moves point forward over a word, dragging
        !          4101: the word preceding or containing point forward as well.  The punctuation
        !          4102: characters between the words do not move.  For example, @w{@samp{FOO, BAR}}
        !          4103: transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.
        !          4104: 
        !          4105:   @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing
        !          4106: two expressions (@pxref{Lists}), and @kbd {C-x C-t} (@code{transpose-lines})
        !          4107: exchanges lines.  They work like @kbd{M-t} except in determining the
        !          4108: division of the text into syntactic units.
        !          4109: 
        !          4110:   A numeric argument to a transpose command serves as a repeat count: it
        !          4111: tells the transpose command to move the character (word, sexp, line) before
        !          4112: or containing point across several other characters (words, sexps, lines).
        !          4113: For example, @kbd{C-u 3 C-t} moves the character before point forward
        !          4114: across three other characters.  This is equivalent to repeating @kbd{C-t}
        !          4115: three times.  @kbd{C-u - 4 M-t} moves the word before point backward across
        !          4116: four words.  @kbd{C-u - C-M-t} would cancel the effect of plain
        !          4117: @kbd{C-M-t}.@refill
        !          4118: 
        !          4119:   A numeric argument of zero is assigned a special meaning (because
        !          4120: otherwise a command with a repeat count of zero would do nothing): to
        !          4121: transpose the character (word, sexp, line) ending after point with the
        !          4122: one ending after the mark.
        !          4123: 
        !          4124: @node Fixing Case, Spelling, Transpose, Fixit
        !          4125: @section Case Conversion
        !          4126: 
        !          4127: @table @kbd
        !          4128: @item M-- M-l
        !          4129: Convert last word to lower case.  @kbd{Meta--} is Meta-minus!
        !          4130: @item M-- M-u
        !          4131: Convert last word to all upper case.
        !          4132: @item M-- M-c
        !          4133: Convert last word to lower case with capital initial.
        !          4134: @end table
        !          4135: 
        !          4136: @findex downcase-word
        !          4137: @findex upcase-word
        !          4138: @findex capitalize-word
        !          4139: @kindex M-- M-l
        !          4140: @kindex M-- M-u
        !          4141: @kindex M-- M-c
        !          4142: @cindex case conversion
        !          4143: @cindex words
        !          4144:   A very common error is to type words in the wrong case.  Because of this,
        !          4145: the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a
        !          4146: special feature when used with a negative argument: they do not move the
        !          4147: cursor.  As soon as you see you have mistyped the last word, you can simply
        !          4148: case-convert it and go on typing.  @xref{Case}.@refill
        !          4149: 
        !          4150: @node Spelling,, Fixing Case, Fixit
        !          4151: @section Checking and Correcting Spelling
        !          4152: @cindex spelling
        !          4153: 
        !          4154: @c doublewidecommands
        !          4155: @table @kbd
        !          4156: @item M-$
        !          4157: Check and correct spelling of word (@code{spell-word}).
        !          4158: @item M-x spell-buffer
        !          4159: Check and correct spelling of each word in the buffer.
        !          4160: @item M-x spell-region
        !          4161: Check and correct spelling of each word in the region.
        !          4162: @item M-x spell-string
        !          4163: Check spelling of specified word.
        !          4164: @end table
        !          4165: 
        !          4166: @kindex M-$
        !          4167: @findex spell-word
        !          4168:   To check the spelling of the word before point, and optionally correct it
        !          4169: as well, use the command @kbd{M-$} (@code{spell-word}).  This command runs
        !          4170: an inferior process containing the @code{spell} program to see whether the
        !          4171: word is correct English.  If it is not, it asks you to edit the word (in
        !          4172: the minibuffer) into a corrected spelling, and then does a @code{query-replace}
        !          4173: to substitute the corrected spelling for the old one throughout the buffer.
        !          4174: 
        !          4175:   If you exit the minibuffer without altering the original spelling, it
        !          4176: means you do not want to do anything to that word.  Then the @code{query-replace}
        !          4177: is not done.
        !          4178: 
        !          4179: @findex spell-buffer
        !          4180:   @kbd{M-x spell-buffer} checks each word in the buffer the same way that
        !          4181: @code{spell-word} does, doing a @code{query-replace} if appropriate for
        !          4182: every incorrect word.@refill
        !          4183: 
        !          4184: @findex spell-region
        !          4185:   @kbd{M-x spell-region} is similar but operates only on the region, not
        !          4186: the entire buffer.
        !          4187: 
        !          4188: @findex spell-string
        !          4189:   @kbd{M-x spell-string} reads a string as an argument and checks whether
        !          4190: that is a correctly spelled English word.  It prints in the echo area a
        !          4191: message giving the answer.
        !          4192: 
        !          4193: @node Files, Buffers, Fixit, Top
        !          4194: @chapter File Handling
        !          4195: @cindex files
        !          4196: 
        !          4197:   The basic unit of stored data in Unix is the @dfn{file}.  To edit a file,
        !          4198: you must tell Emacs to examine the file and prepare a buffer containing a
        !          4199: copy of the file's text.  This is called @dfn{visiting} the file.  Editing
        !          4200: commands apply directly to text in the buffer; that is, to the copy inside
        !          4201: Emacs.  Your changes appear in the file itself only when you @dfn{save} the
        !          4202: buffer back into the file.
        !          4203: 
        !          4204:   In addition to visiting and saving files, Emacs can delete, copy, rename,
        !          4205: and append to files, and operate on file directories.
        !          4206: 
        !          4207: @menu
        !          4208: * File Names::   How to type and edit file name arguments.
        !          4209: * Visiting::     Visiting a file prepares Emacs to edit the file.
        !          4210: * Saving::       Saving makes your changes permanent.
        !          4211: * Reverting::    Reverting cancels all the changes not saved.
        !          4212: * Auto Save::    Auto Save periodically protects against loss of data.
        !          4213: * ListDir::      Listing the contents of a file directory.
        !          4214: * Dired::        ``Editing'' a directory to delete, rename, etc.
        !          4215:                   the files in it.
        !          4216: * Misc File Ops:: Other things you can do on files.
        !          4217: @end menu
        !          4218: 
        !          4219: @node File Names,, Files, Files
        !          4220: @section File Names
        !          4221: @cindex file names
        !          4222: 
        !          4223:   Most Emacs commands that operate on a file require you to specify the
        !          4224: file name.  (Saving and reverting are exceptions; the buffer knows which
        !          4225: file name to use for them.)  File names are specified using the minibuffer
        !          4226: (@pxref{Minibuffer}).  @dfn{Completion} is available, to make it easier to
        !          4227: specify long file names.  @xref{Completion}.
        !          4228: 
        !          4229:   There is always a @dfn{default file name} which will be used if you type
        !          4230: just @key{RET}, entering an empty argument.  Normally the default file name
        !          4231: is the name of the file visited in the current buffer; this makes it easy
        !          4232: to operate on that file with any of the Emacs file commands.
        !          4233: 
        !          4234: @vindex default-directory
        !          4235:   Each buffer has a default directory, normally the same as the directory
        !          4236: of the file visited in that buffer.  When Emacs reads a file name, if you
        !          4237: do not specify a directory, the default directory is used.  If you specify
        !          4238: a directory in a relative fashion, with a name that does not start with a
        !          4239: slash, it is interpreted with respect to the default directory.  The
        !          4240: default directory is kept in the variable @code{default-directory}, which
        !          4241: has a separate value in every buffer.
        !          4242: 
        !          4243:   For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
        !          4244: the default directory is @file{/u/rms/gnu/}.  If you type just @samp{foo},
        !          4245: which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
        !          4246: @samp{../.login} would stand for @file{/u/rms/.login}.  @samp{new/foo}
        !          4247: would stand for the filename @file{/u/rms/gnu/new/foo}.
        !          4248: 
        !          4249:   The default directory actually appears initially in the minibuffer when
        !          4250: the file name is read.  This serves two purposes: it shows you what the
        !          4251: default is, so that you can type a relative file name and know with
        !          4252: certainty what it will mean, and it allows you to edit the default to
        !          4253: specify a different directory.
        !          4254: 
        !          4255:   Note that it is legitimate to type an absolute file name after you enter
        !          4256: the minibuffer, ignoring the presence of the default directory name as part
        !          4257: of the text.  The final minibuffer contents may look invalid, but that is
        !          4258: not so.  @xref{Minibuffer File}.
        !          4259: 
        !          4260:   The command @kbd{M-x pwd} prints the current buffer's default directory,
        !          4261: and the command @kbd{M-x cd} sets it (to a value read using the
        !          4262: minibuffer).  A buffer's default directory changes only when the @code{cd}
        !          4263: command is used.  A file-visiting buffer's default directory is initialized
        !          4264: to the directory of the file that is visited there.  If a buffer is made
        !          4265: randomly with @kbd{C-x b}, its default directory is copied from that of the
        !          4266: buffer that was current at the time.
        !          4267: 
        !          4268: @node Visiting, Saving, File Names, Files
        !          4269: @section Visiting Files
        !          4270: @cindex visiting files
        !          4271: 
        !          4272: @c WideCommands
        !          4273: @table @kbd
        !          4274: @item C-x C-f
        !          4275: Visit a file (@code{find-file}).
        !          4276: @item C-x C-v
        !          4277: Visit a different file instead of the one visited last
        !          4278: (@code{find-alternate-file}).
        !          4279: @item C-x 4 C-f
        !          4280: Visit a file, in another window (@code{find-file-other-window}).  Don't
        !          4281: change this window.
        !          4282: @end table
        !          4283: 
        !          4284: @cindex files
        !          4285: @cindex visiting
        !          4286: @cindex saving
        !          4287: @vindex ask-about-buffer-names
        !          4288:   @dfn{Visiting} a file means copying its contents into Emacs where you can
        !          4289: edit them.  Emacs makes a new buffer for each file that you visit.  We say
        !          4290: that the buffer is visiting the file that it was created to hold.  Emacs
        !          4291: constructs the buffer name from the file name by throwing away the
        !          4292: directory, keeping just the name proper.  For example, a file named
        !          4293: @file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}.  If
        !          4294: there is already a buffer with that name, a unique name is constructed by
        !          4295: appending @samp{<2>}, @samp{<3>}, or so on, using the lowest number that
        !          4296: makes a name that is not already in use.  If the variable
        !          4297: @code{ask-about-buffer-names} is non-@code{nil}, the user is asked what
        !          4298: buffer name to use; this takes the place of automatic uniquization.
        !          4299: 
        !          4300:   Each window's mode line shows the name of the buffer that is being displayed
        !          4301: in that window, so you can always tell what buffer you are editing.
        !          4302: 
        !          4303:   The changes you make with Emacs are made in the Emacs buffer.  They do
        !          4304: not take effect in the file that you visited, or any place permanent, until
        !          4305: you @dfn{save} the buffer.  Saving the buffer means that Emacs writes the
        !          4306: current contents of the buffer into its visited file.  @xref{Saving}.
        !          4307: 
        !          4308: @cindex modified (buffer)
        !          4309:   If a buffer contains changes that have not been saved, the buffer is said
        !          4310: to be @dfn{modified}.  This is important because it implies that some
        !          4311: changes will be lost if the buffer is not saved.  The mode line displays
        !          4312: two stars near the left margin if the buffer is modified.
        !          4313: 
        !          4314: @kindex C-x C-f
        !          4315: @findex find-file
        !          4316:   To visit a file, use the command @kbd{C-x C-f} (@code{find-file}).  Follow
        !          4317: the command with the name of the file you wish to visit, terminated by a
        !          4318: @key{RET}.
        !          4319: 
        !          4320:   The file name is read using the minibuffer (@pxref{Minibuffer}), with
        !          4321: defaulting and completion in the standard manner (@pxref{File Names}).
        !          4322: While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
        !          4323: 
        !          4324:   Your confirmation that @kbd{C-x C-f} has completed successfully is the
        !          4325: appearance of new text on the screen and a new buffer name in the mode
        !          4326: line.  If the specified file does not exist and could not be created, or
        !          4327: cannot be read, then an error results.  The error message is printed in the
        !          4328: echo area, and includes the file name which Emacs was trying to visit.
        !          4329: 
        !          4330:   If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
        !          4331: another copy.  It selects the existing buffer containing that file.
        !          4332: However, before doing so, it checks that the file itself has not changed
        !          4333: since you visited or saved it last.  If the file has changed, a warning
        !          4334: message is printed.  @xref{Interlocking,,Simultaneous Editing}.
        !          4335: 
        !          4336: @cindex creating files
        !          4337:   What if you want to create a file?  Just visit it.  Emacs prints
        !          4338: @samp{(New File)} in the echo area, but in other respects behaves as if you
        !          4339: had visited an existing empty file.  If you make any changes and save them,
        !          4340: the file is created.
        !          4341: 
        !          4342: @kindex C-x C-v
        !          4343: @findex find-alternate-file
        !          4344:   If you visit a nonexistent file unintentionally (because you typed the
        !          4345: wrong file name), use the @kbd{C-x C-v} (@code{find-alternate-file})
        !          4346: command to visit the file you wanted.  @kbd{C-x C-v} is similar to @kbd{C-x
        !          4347: C-f}, but it kills the current buffer (after first offering to save it if
        !          4348: it is modified).@refill
        !          4349: 
        !          4350: @vindex find-file-run-dired
        !          4351:   If the file you specify is actually a directory, Dired is called on that
        !          4352: directory (@pxref{Dired}).  This can be inhibited by setting the variable
        !          4353: @code{find-file-run-dired} to @code{nil}; then it is an error to try to
        !          4354: visit a directory.
        !          4355: 
        !          4356: @kindex C-x 4 f
        !          4357: @findex find-file-other-window
        !          4358:   @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
        !          4359: except that the buffer containing the specified file is selected in another
        !          4360: window.  The window that was selected before @kbd{C-x 4 f} continues to
        !          4361: show the same buffer it was already showing.  If this command is used when
        !          4362: only one window is being displayed, that window is split in two, with one
        !          4363: window showing the same before as before, and the other one showing the
        !          4364: newly requested buffer.
        !          4365: 
        !          4366: @node Saving, Reverting, Visiting, Files
        !          4367: @section Saving Files
        !          4368: 
        !          4369:   @dfn{Saving} a buffer in Emacs means writing its contents back into the file
        !          4370: that was visited in the buffer.
        !          4371: 
        !          4372: @table @kbd
        !          4373: @item C-x C-s
        !          4374: Save the current buffer in its visited file (@code{save-buffer}).
        !          4375: @item C-x s
        !          4376: Save any or all buffers in their visited files (@code{save-some-buffers}).
        !          4377: @item M-~
        !          4378: Forget that the current buffer has been changed (@code{not-modified}).
        !          4379: @item C-x C-w
        !          4380: Save the current buffer in a specified file, and record that file as
        !          4381: the one visited in the buffer (@code{write-file}).
        !          4382: @item M-x set-visited-file-name
        !          4383: Mark the current buffer as visiting a specified file.
        !          4384: @end table
        !          4385: 
        !          4386: @kindex C-x C-s
        !          4387: @findex save-buffer
        !          4388:   When you wish to save the file and make your changes permanent, type
        !          4389: @kbd{C-x C-s} (@code{save-buffer}).  After saving is finished, @kbd{C-x C-s}
        !          4390: prints a message such as
        !          4391: 
        !          4392: @example
        !          4393: Wrote /u/rms/gnu/gnu.tasks
        !          4394: @end example
        !          4395: 
        !          4396: @noindent
        !          4397: If the selected buffer is not modified (no changes have been made in it
        !          4398: since the buffer was created or last saved), saving is not really done,
        !          4399: because it would be redundant.  Instead, @kbd{C-x C-s} prints a message in
        !          4400: the echo area saying
        !          4401: 
        !          4402: @example
        !          4403: (No changes need to be written)
        !          4404: @end example
        !          4405: 
        !          4406: @kindex C-x s
        !          4407: @findex save-some-buffers
        !          4408:   The command @kbd{C-x s} (@code{save-some-buffers}) can save any or all modified
        !          4409: buffers.  First it asks, for each modified buffer, whether to save it.
        !          4410: These questions appear as typeout, overlying the buffer text, and should
        !          4411: be answered with @kbd{y} or @kbd{n}.  After all questions have been asked,
        !          4412: the buffers you have approved are all saved.
        !          4413: 
        !          4414: @kindex M-~
        !          4415: @findex not-modified
        !          4416:   If you have changed a buffer and do not want the changes to be saved, you
        !          4417: should take some action to prevent it.  Otherwise, each time you use
        !          4418: @code{save-some-buffers} you are liable to save it by mistake.  One thing
        !          4419: you can do is type @kbd{M-~} (@code{not-modified}), which clears out the
        !          4420: indication that the buffer is modified.  If you do this, none of the save
        !          4421: commands will believe that the buffer needs to be saved.  (If we take
        !          4422: @samp{~} to mean `not', then @kbd{Meta-~} is `not', metafied.)  You could
        !          4423: also use @code{set-visited-file-name} (see below) to mark the buffer as
        !          4424: visiting a different file name, one which is not in use for anything
        !          4425: important.  Alternatively, you can undo all the changes made since the file
        !          4426: was visited or saved, by reading the text from the file again.  This is
        !          4427: called @dfn{reverting}.  @xref{Reverting}.  You could also undo all the
        !          4428: changes by repeating the undo command @kbd{C-x u} until you have undone all
        !          4429: the changes; but this only works if you have not made more changes than the
        !          4430: undo mechanism can remember.
        !          4431: 
        !          4432: @findex set-visited-file-name
        !          4433:   @kbd{M-x set-visited-file-name} alters the name of the file that the
        !          4434: current buffer is visiting.  It reads the new file name using the
        !          4435: minibuffer.  It can be used on a buffer that is not visiting a file, too.
        !          4436: The buffer's name is changed to correspond to the file it is now visiting
        !          4437: in the usual fashion (unless the new name is in use already for some other
        !          4438: buffer; in that case, the buffer name is not changed).
        !          4439: @code{set-visited-file-name} does not save the buffer in the newly visited
        !          4440: file; it just alters the records inside Emacs so that, if you save the
        !          4441: buffer, it will be saved in that file.  It also marks the buffer as
        !          4442: ``modified'' so that @kbd{C-x C-s} @i{will} save.
        !          4443: 
        !          4444: @kindex C-x C-w
        !          4445: @findex write-file
        !          4446:   If you wish to mark the buffer as visiting different file and save it
        !          4447: right away, use @kbd{C-x C-w} (@code{write-file}).  It is precisely
        !          4448: equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
        !          4449: @kbd{C-x C-s} used on a buffer that is not visiting with a file has the
        !          4450: same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
        !          4451: buffer as visiting that file, and saves it there.  The default file name in
        !          4452: a buffer that is not visiting a file is made by combining the buffer name
        !          4453: with the buffer's default directory.
        !          4454: 
        !          4455:   If Emacs is about to save a file and sees that the date of the latest
        !          4456: version on disk does not match what Emacs last read or wrote, Emacs
        !          4457: notifies you of this fact, because it probably indicates a problem caused
        !          4458: by simultaneous editing and requires your immediate attention.
        !          4459: @xref{Interlocking,, Simultaneous Editing}.
        !          4460: 
        !          4461: @vindex require-final-newline
        !          4462:   If the variable @code{require-final-newline} is non-@code{nil}, Emacs
        !          4463: puts a newline at the end of any file that doesn't already end in one,
        !          4464: every time a file is saved or written.
        !          4465: 
        !          4466: @menu
        !          4467: * Backup::       How Emacs saves the old version of your file.
        !          4468: * Interlocking:: How Emacs protects against simultaneous editing
        !          4469:                   of one file by two users.
        !          4470: @end menu
        !          4471: 
        !          4472: @node Backup, Interlocking, Saving Saving
        !          4473: @subsection Backup Files
        !          4474: @cindex backup file
        !          4475: 
        !          4476:   Because Unix does not provide version numbers in file names, rewriting a
        !          4477: file in Unix automatically destroys all record of what the file used to
        !          4478: contain.  Thus, saving a file from Emacs throws away the old contents of
        !          4479: the file---or it would, except that Emacs carefully copies the old contents
        !          4480: to another file, called the @dfn{backup} file, before actually saving.
        !          4481: At your option, Emacs can keep either a single backup file or a series of
        !          4482: numbered backup files for each file that you edit.
        !          4483: 
        !          4484:   Emacs makes a backup for a file only the first time the file is saved
        !          4485: from one buffer.  No matter how many times you save a file, its backup file
        !          4486: continues to contain the contents from before the file was visited.
        !          4487: Normally this means that the backup file contains the contents from before
        !          4488: the current editing session; however, if you kill the buffer and then visit
        !          4489: the file again, a new backup file will be made by the next save.
        !          4490: 
        !          4491:   If you choose to have a single backup file (this is the default),
        !          4492: the backup file's name is constructed by appending @samp{~} to the
        !          4493: file name being edited; thus, the backup file for @file{eval.c} would
        !          4494: be @file{eval.c~}.
        !          4495: 
        !          4496:   If you choose to have a series of numbered backup files, backup file
        !          4497: names are made by appending @samp{.~}, the number, and another @samp{~} to
        !          4498: the original file name.  Thus, the backup files of @file{eval.c} would be
        !          4499: called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
        !          4500: like @file{eval.c.~259~} and beyond.
        !          4501: 
        !          4502: @vindex version-control
        !          4503:   The choice of single backup or numbered backups is controlled by the
        !          4504: variable @code{version-control}.  Its possible values are
        !          4505: 
        !          4506: @table @code
        !          4507: @item t
        !          4508: Make numbered backups.
        !          4509: @item nil
        !          4510: Make numbered backups for files that have numbered backups already.
        !          4511: @item never
        !          4512: Do not in any case make numbered backups.
        !          4513: @end table
        !          4514: 
        !          4515: @noindent
        !          4516: @code{version-control} may be set locally in an individual buffer to
        !          4517: control the making of backups for that buffer's file.  For example,
        !          4518: Rmail mode locally sets @code{version-control} to @code{never} to make sure
        !          4519: that there is only one backup for an Rmail file.  @xref{Locals}.
        !          4520: 
        !          4521: @vindex make-backup-files
        !          4522:   If the variable @code{make-backup-files} is set to @code{nil}, backup
        !          4523: files are not written at all.
        !          4524: 
        !          4525: @subsubsection Automatic Deletion of Backups
        !          4526: 
        !          4527: @vindex kept-old-versions
        !          4528: @vindex kept-new-versions
        !          4529:   To prevent unlimited consumption of disk space, Emacs can delete numbered
        !          4530: backup versions automatically.  Generally Emacs keeps the first few backups
        !          4531: and the latest few backups, deleting any in between.  This happens every
        !          4532: time a new backup is made.  The two variables that control the deletion are
        !          4533: @code{kept-old-versions} and @code{kept-new-versions}.  Their values are, respectively
        !          4534: the number of oldest (lowest-numbered) backups to keep and the number of
        !          4535: newest (highest-numbered) ones to keep, each time a new backup is made.
        !          4536: Recall that these values are used just after a new backup version is made;
        !          4537: that newly made backup is included in the count in @code{kept-new-versions}.
        !          4538: By default, both variables are 2.
        !          4539: 
        !          4540: @vindex trim-versions-without-asking
        !          4541:   If @code{trim-versions-without-asking} is non-@code{nil}, the excess
        !          4542: middle versions are deleted without a murmur.  If it is @code{nil}, the
        !          4543: default, then you are asked whether the excess middle versions should
        !          4544: really be deleted.
        !          4545: 
        !          4546:   Dired's @kbd{.} command can also be used to delete old versions;
        !          4547: @xref{Dired}.
        !          4548: 
        !          4549: @subsubsection Copying vs.@: Renaming
        !          4550: 
        !          4551:   Backup files can be made by copying the old file or by renaming it.  This
        !          4552: makes a difference when the old file has multiple names.  If the old file
        !          4553: is renamed into the backup file, then the alternate names become names for
        !          4554: the backup file.  If the old file is copied instead, then the alternate
        !          4555: names remain names for the file that you are editing, and the contents
        !          4556: accessed by those names will be the new contents.
        !          4557: 
        !          4558: @vindex backup-by-copying
        !          4559: @vindex backup-by-copying-when-linked
        !          4560:   The choice of renaming or copying is controlled by two variables.
        !          4561: Normally, renaming is done.  If the variable @code{backup-by-copying} is
        !          4562: non-@code{nil}, copying is used.  If the variable @code{backup-by-copying-when-linked}
        !          4563: is non-@code{nil}, then copying is done for files that have multiple names,
        !          4564: but renaming is done when the file being edited has only one name.  (For
        !          4565: files with only one name, the major difference between renaming and copying
        !          4566: is that renaming is faster.)
        !          4567: 
        !          4568: @node Interlocking,,Backup,Saving
        !          4569: @subsection Protection against Simultaneous Editing
        !          4570: 
        !          4571: @cindex file dates
        !          4572: @cindex simultaneous editing
        !          4573:   Simultaneous editing occurs when two users visit the same file, both make
        !          4574: changes, and then both save them.  If nobody were informed that this was
        !          4575: happening, whichever user saved first would later find that his changes
        !          4576: were lost.  On some systems, Emacs notices immediately when the second user
        !          4577: starts to change the file, and issues an immediate warning.  When this is
        !          4578: not possible, or if the second user has gone on to change the file despite
        !          4579: the warning, Emacs checks later when the file is saved, and issues a second
        !          4580: warning when a user is about to overwrite a file containing another user's
        !          4581: changes.  If the editing user takes the proper corrective action at this
        !          4582: point, he can prevent actual loss of work.
        !          4583: 
        !          4584: @findex ask-user-about-lock
        !          4585:   When you make the first modification in an Emacs buffer that is visiting
        !          4586: a file, Emacs records that you have locked the file.  (It does this by
        !          4587: writing another file in a directory reserved for this purpose).  The lock
        !          4588: is removed when you save the changes.  The idea is that the file is locked
        !          4589: whenever the buffer is modified.  If you begin to modify the buffer while
        !          4590: the visited file is locked by someone else, this constitutes a collision,
        !          4591: and Emacs asks you what to do.  It does this by calling the Lisp function
        !          4592: @code{ask-user-about-lock}, which you can redefine for the sake of
        !          4593: customization.  The standard definition of this function asks you a
        !          4594: question and accepts three possible answers:
        !          4595: 
        !          4596: @table @kbd
        !          4597: @item s
        !          4598: Steal the lock.  Whoever was already changing the file loses the lock,
        !          4599: and you gain the lock.
        !          4600: @item p
        !          4601: Proceed.  Go ahead and edit the file despite its being locked by someone else.
        !          4602: @item q
        !          4603: Quit.  This causes an error (@code{file-locked}) and the modification you
        !          4604: were trying to make in the buffer does not actually take place.
        !          4605: @end table
        !          4606: 
        !          4607:   Note that locking works on the basis of a file name; if a file has
        !          4608: multiple names, Emacs does not realize that the two names are the same file
        !          4609: and cannot prevent two user from editing it simultaneously under different
        !          4610: names.  However, basing locking on names means that Emacs can interlock the
        !          4611: editing of new files that will not really exist until they are saved.
        !          4612: 
        !          4613:   Some systems are not configured to allow Emacs to make locks.  On
        !          4614: these systems, Emacs cannot detect trouble in advance, but it still can
        !          4615: detect it in time to prevent you from overwriting someone else's changes.
        !          4616: 
        !          4617:   Every time Emacs saves a buffer, it first checks the last-modification
        !          4618: date of the existing file on disk to see that it has not changed since the
        !          4619: file was last visited or saved.  If the date does not match, it implies
        !          4620: that changes were made in the file in some other way, and these changes are
        !          4621: about to be lost if Emacs actually does save.  To prevent this, Emacs
        !          4622: prints a warning message and asks for confirmation before saving.
        !          4623: Occasionally you will know why the file was changed and know that it does
        !          4624: not matter; then you can answer `yes' and proceed.  Otherwise, you should
        !          4625: cancel the save with @kbd{C-g} and investigate the situation.
        !          4626: 
        !          4627:   The first thing you should do when notified that simultaneous editing has
        !          4628: already taken place is to list the directory with @kbd{C-u C-x C-d}
        !          4629: (@pxref{ListDir,,Directory Listing}).  This will show the file's current
        !          4630: author.  You should attempt to contact him to warn him not to continue
        !          4631: editing.  Often the next step is to save the contents of your Emacs buffer
        !          4632: under a different name, and use @code{diff} to compare the two
        !          4633: files.@refill
        !          4634: 
        !          4635:   Simultaneous editing checks are also made when you visit with @kbd{C-x
        !          4636: C-f} a file that is already visited.  This is not strictly necessary, but
        !          4637: it can cause you to find out about the problem earlier, when perhaps
        !          4638: correction takes less work.
        !          4639: 
        !          4640: @node Reverting, Auto Save, Saving, Files
        !          4641: @section Reverting a Buffer
        !          4642: @findex revert-buffer
        !          4643: @cindex drastic changes
        !          4644: 
        !          4645:   If you have made extensive changes to a file and then change your mind
        !          4646: about them, you can get rid of them by reading in the previous version of
        !          4647: the file.  To do this, use @kbd{M-x revert-buffer}, which operates on the
        !          4648: current buffer.  Since this is a very dangerous thing to do, you must
        !          4649: confirm it with `yes'.
        !          4650: 
        !          4651:   If the current buffer has been auto-saved more recently than it has been
        !          4652: saved for real, @code{revert-buffer} offers to read the auto save file
        !          4653: instead of the visited file.  This question comes before the usual request
        !          4654: for confirmation, and demands @kbd{y} or @kbd{n} as an answer.  If you have
        !          4655: started to type @kbd{yes} for confirmation without realizing that the other
        !          4656: question was going to be asked, the @kbd{y} will answer that question, but
        !          4657: the @kbd{es} will not be valid confirmation.  So you will have a chance to
        !          4658: cancel the operation with @kbd{C-g} and try it again with the answers that
        !          4659: you really intend.
        !          4660: 
        !          4661:   @code{revert-buffer} keeps point at the same distance (measured in
        !          4662: characters) from the beginning of the file.  If the file was edited only
        !          4663: slightly, you will be at approximately the same piece of text after
        !          4664: reverting as before.  If you have made drastic changes, the same value of
        !          4665: point in the old file may address a totally different piece of text.
        !          4666: 
        !          4667:   A buffer reverted from its visited file is marked ``not modified'' until
        !          4668: another change is made.
        !          4669: 
        !          4670:   Some kinds of buffers whose contents reflect data bases other than files,
        !          4671: such as Dired buffers, can also be reverted.  For them, reverting means
        !          4672: recalculating their contents from the appropriate data base.  Buffers
        !          4673: created randomly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
        !          4674: reports an error when asked to do so.
        !          4675: 
        !          4676: @node Auto Save, ListDir, Reverting, Files
        !          4677: @section Auto Saving: Protection Against Disasters
        !          4678: @cindex Auto Save mode
        !          4679: @cindex crashes
        !          4680: 
        !          4681:   Emacs saves all the visited files from time to time (based on counting
        !          4682: your keystrokes) without being asked.  This is called @dfn{auto-saving}.
        !          4683: It prevents you from losing more than a limited amount of work if the
        !          4684: system crashes.
        !          4685: 
        !          4686: @vindex auto-save-visited-file-name
        !          4687:   Auto-saving does not normally save in the files that you visited, because
        !          4688: it can be very undesirable to save a program that is in an inconsistent
        !          4689: state because you have made half of a planned change.  Instead, auto-saving
        !          4690: is done in a different file called the @dfn{auto-save file}, and the
        !          4691: visited file is changed only when you request saving explicitly (such as
        !          4692: with @kbd{C-x C-s}).  If you want auto-saving to be done in the visited
        !          4693: file, set the variable @code{auto-save-visited-file-name} to be non-@code{nil}.
        !          4694: The file name to be used for auto-saving in a buffer is calculated when
        !          4695: auto-saving is turned on in that buffer, based on the variable values in
        !          4696: effect at that time.
        !          4697: 
        !          4698:   Normally, the auto-save file name is made by appending @samp{#} to the
        !          4699: front of the visited file name.  Thus, a buffer visiting file @file{foo.c}
        !          4700: would be auto-saved in a file @file{#foo.c}.  Most buffers that are not
        !          4701: visiting files are auto-saved only if you request it explicitly; when they
        !          4702: are auto-saved, the auto-save file name is made by appending @samp{#%} to
        !          4703: the buffer name.  For example, the @samp{*mail*} buffer in which you
        !          4704: compose messages to be sent is auto-saved in a file named @file{#%*mail*}.
        !          4705: Auto-save file names are made this way unless you reprogram parts of Emacs
        !          4706: to do something different.
        !          4707: 
        !          4708: @vindex auto-save-default
        !          4709: @findex auto-save-mode
        !          4710:   Each time you visit a file, auto saving is turned on for that file's
        !          4711: buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
        !          4712: in batch mode; @pxref{Entering Emacs}).  The default for this variable is
        !          4713: @code{t}, so auto-saving is the usual practice for file-visiting buffers.
        !          4714: Auto-saving can be turned on or off for any existing buffer with the
        !          4715: command @kbd{M-x auto-save-mode}.  Like other minor mode commands, @kbd{M-x
        !          4716: auto-save-mode} turns auto-saving on with a positive argument, off with a
        !          4717: zero or negative argument; with no argument, it toggles.
        !          4718: 
        !          4719: @vindex auto-save-interval
        !          4720: @findex do-auto-save
        !          4721:   Emacs does auto-saving every so often, based on counting how many
        !          4722: characters you have typed since the last time auto-saving was done.  The
        !          4723: variable @code{auto-save-interval} specifies how many characters there are
        !          4724: between auto-saves.  By default, it is 300.  Emacs also auto-saves whenever
        !          4725: you call the function @code{do-auto-save}.
        !          4726: 
        !          4727:   Emacs also does auto-saving whenever it gets a fatal error.  This
        !          4728: includes killing the Emacs job with a shell command such as @code{kill
        !          4729: %emacs}, or disconnecting a phone line or network connection.
        !          4730: 
        !          4731:   When Emacs determines that it is time for auto-saving, each buffer is
        !          4732: considered, and is auto-saved if auto-saving is turned on for it and it has
        !          4733: been changed since the last time it was auto-saved.  If any auto-saving is
        !          4734: done, the message @samp{Auto-saving...} is displayed in the echo area until
        !          4735: auto-saving is finished.  Errors occurring during auto-saving are trapped
        !          4736: so that they do not interfere with the execution of commands you have been
        !          4737: typing.
        !          4738: 
        !          4739: @vindex delete-auto-save-files
        !          4740:   A buffer's auto-save file is deleted when you save the buffer in its
        !          4741: visited file.  To inhibit this, set the variable @code{delete-auto-save-files}
        !          4742: to @code{nil}.
        !          4743: 
        !          4744: @findex recover-file
        !          4745:   The way to use the contents of an auto save file to recover from a loss
        !          4746: of data is with the command @kbd{M-x recover-file @key{RET} @var{file}
        !          4747: @key{RET}}.  This visits @var{file} and then (after your confirmation) it
        !          4748: from its auto-save file @file{#@var{file}}.  You can then save with
        !          4749: @kbd{C-x C-s} to put the recovered text into @var{file} itself.  For
        !          4750: example, to recover file @file{foo.c} from its auto-save file
        !          4751: @file{#foo.c}, do:@refill
        !          4752: 
        !          4753: @example
        !          4754: M-x recover-file @key{RET} foo.c @key{RET}
        !          4755: C-x C-s
        !          4756: @end example
        !          4757: 
        !          4758: @node ListDir, Dired, Auto Save, Files
        !          4759: @section Listing a File Directory
        !          4760: 
        !          4761: @cindex file directory
        !          4762: @cindex directory listing
        !          4763:   Files are classified by Unix into @dfn{directories}.  A @dfn{directory
        !          4764: listing} is a list of all the files in a directory.  Emacs provides
        !          4765: directory listings in brief format (file names only) and verbose format
        !          4766: (sizes, dates, and authors included).
        !          4767: 
        !          4768: @table @kbd
        !          4769: @item C-x C-d @var{dir-or-pattern}
        !          4770: Print a brief directory listing (@code{list-directory}).
        !          4771: @item C-u C-x C-d @var{dir-or-pattern}
        !          4772: Print a verbose directory listing.
        !          4773: @end table
        !          4774: 
        !          4775: @findex list-directory
        !          4776: @kindex C-x C-d
        !          4777:   The command to print a directory listing is @kbd{C-x C-d} (@code{list-directory}).
        !          4778: It reads using the minibuffer a file name which is either a directory to be
        !          4779: listed or a wildcard-containing pattern for the files to be listed.  For
        !          4780: example,
        !          4781: 
        !          4782: @example
        !          4783: C-x C-d /u2/emacs/etc @key{RET}
        !          4784: @end example
        !          4785: 
        !          4786: @noindent
        !          4787: lists all the files in directory @file{/u2/emacs/etc}.  An example of
        !          4788: specifying a file name pattern is
        !          4789: 
        !          4790: @example
        !          4791: C-x C-d /u2/emacs/src/*.c @key{RET}
        !          4792: @end example
        !          4793: 
        !          4794:   Normally, @kbd{C-x C-d} prints a brief directory listing containing just
        !          4795: file names.  A numeric argument (regardless of value) tells it to print a
        !          4796: verbose listing (like @code{ls -l}).
        !          4797: 
        !          4798: @vindex list-directory-brief-switches
        !          4799: @vindex list-directory-verbose-switches
        !          4800:   The text of a directory listing is obtained by running @code{ls} in an
        !          4801: inferior process.  Two Emacs variables control the switches passed to
        !          4802: @code{ls}: @code{list-directory-brief-switches} is a string giving the
        !          4803: switches to use in brief listings (@code{"-CF"} by default), and
        !          4804: @code{list-directory-verbose-switches} is a string giving the switches to
        !          4805: use in a verbose listing (@code{"-l"} by default).
        !          4806: 
        !          4807: @node Dired, Misc File Ops, ListDir, Files
        !          4808: @section Dired, the Directory Editor
        !          4809: @cindex Dired
        !          4810: @cindex deletion (of files)
        !          4811: 
        !          4812:   Dired makes it easy to delete or visit many of the files in a single
        !          4813: directory at once.  It makes an Emacs buffer containing a listing of the
        !          4814: directory.  You can use the normal Emacs commands to move around in this
        !          4815: buffer, and special Dired commands to operate on the files.
        !          4816: 
        !          4817: @findex dired
        !          4818: @kindex C-x d
        !          4819: @vindex dired-listing-switches
        !          4820:   To invoke dired, do @kbd{C-x d} or @kbd{M-x dired}.  The command reads a
        !          4821: directory name or wildcard file name pattern as a minibuffer argument just
        !          4822: like the @code{list-directory} command, @kbd{C-x C-d}.  Where @code{dired}
        !          4823: differs from @code{list-directory} is in naming the buffer after the
        !          4824: directory name or the wildcard pattern used for the listing, and putting
        !          4825: the buffer into Dired mode so that the special commands of Dired are
        !          4826: available in it.  The variable @code{dired-listing-switches} is a string
        !          4827: used as an argument to @code{ls} in making the directory; this string
        !          4828: @i{must} contain @samp{-l}.
        !          4829: 
        !          4830: @findex dired-other-window
        !          4831: @kindex C-x 4 d
        !          4832:   To display the Dired buffer in another window rather than in the selected
        !          4833: window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead of @kbd{C-x d}.
        !          4834: 
        !          4835:   Once the Dired buffer exists, you can switch freely between it and other
        !          4836: Emacs buffers.  Whenever the Dired buffer is selected, certain special
        !          4837: commands are provided that operate on files that are listed.  The Dired
        !          4838: buffer is ``read-only'', and inserting text in it is not useful, so
        !          4839: ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired
        !          4840: commands.  Most Dired commands operate on the file described by the line
        !          4841: that point is on.  Some commands perform operations immediately; others
        !          4842: ``flag'' the file to be operated on later.
        !          4843: 
        !          4844:   Most Dired commands that operate on the current line's file also treat a
        !          4845: numeric argument a repeat count, meaning to apply to the files of the next
        !          4846: few lines.  A negative argument means to operate on the files of the
        !          4847: preceding lines, and leave point on the first of those lines.
        !          4848: 
        !          4849:   All the usual Emacs cursor motion commands are available in Dired
        !          4850: buffers.  Some special purpose commands are also provided.  The keys
        !          4851: @kbd{C-n} and @kbd{C-p} are redefined so that they try to position
        !          4852: the cursor at the beginning of the filename on the line, rather than
        !          4853: at the beginning of the line.
        !          4854: 
        !          4855:   For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to
        !          4856: @kbd{C-n}.  @kbd{p} is equivalent to @kbd{C-p}.  Moving by lines is done so
        !          4857: often in Dired that it deserves to be easy to type.  @key{DEL} (move up and
        !          4858: unflag) is often useful simply for moving up.@refill
        !          4859: 
        !          4860: @section Deleting Files with Dired
        !          4861: 
        !          4862:   The primary use of Dired is to flag files for deletion and then delete
        !          4863: them.
        !          4864: 
        !          4865: @table @kbd
        !          4866: @item d
        !          4867: Flag this file for deletion.
        !          4868: @item u
        !          4869: Remove deletion-flag on this line.
        !          4870: @item @key{DEL}
        !          4871: Remove deletion-flag on previous line, moving point to that line.
        !          4872: @item x
        !          4873: Delete the files that are flagged for deletion.
        !          4874: @item #
        !          4875: Flag all auto-save files (files whose names start with @samp{#}) for
        !          4876: deletion (@pxref{Auto Save}).
        !          4877: @item ~
        !          4878: Flag all backup files (files whose names end with @samp{~}) for deletion
        !          4879: (@pxref{Backup}).
        !          4880: @item .
        !          4881: Flag excess numeric backup files for deletion.  The oldest and newest
        !          4882: few backup files of any one file are exempt; the middle ones are flagged.
        !          4883: @end table
        !          4884: 
        !          4885:   You can flag a file for deletion by moving to the line describing the
        !          4886: file and typing @kbd{d} or @kbd{C-d}.  The deletion flag is visible as a
        !          4887: @samp{D} at the beginning of the line.  Point is moved to the beginning of
        !          4888: the next line, so that repeated @kbd{d} commands flag successive files.
        !          4889: 
        !          4890:   The files are flagged for deletion rather than deleted immediately to
        !          4891: avoid the danger of deleting a file accidentally.  Until you direct Dired
        !          4892: to delete the flagged files, you can remove deletion flags using the
        !          4893: commands @kbd{u} and @key{DEL}.  @kbd{u} works just like @kbd{d}, but
        !          4894: removes flags rather than making flags.  @key{DEL} moves upward, removing
        !          4895: flags; it is like @kbd{u} with numeric argument automatically negated.
        !          4896: 
        !          4897:   To delete the flagged files, type @kbd{x}.  This command first displays a
        !          4898: list of all the file names flagged for deletion, and requests confirmation
        !          4899: with `yes'.  Once you confirm, all the flagged files are deleted, and their
        !          4900: lines are deleted from the text of the Dired buffer.  The shortened Dired
        !          4901: buffer remains selected.  If you answer `no' or quit with @kbd{C-g}, you
        !          4902: return immediately to Dired, with the deletion flags still present and no
        !          4903: files actually deleted.
        !          4904: 
        !          4905:   The @kbd{#}, @kbd{~} and @kbd{.} commands flags many files for
        !          4906: deletion, based on their names.  These commands are useful precisely
        !          4907: because they do not actually delete any files; you can remove the
        !          4908: deletion flags from any flagged files that you really wish to keep.@refill
        !          4909: 
        !          4910:   @kbd{#} flags for deletion all files that appear to have been made
        !          4911: by auto-saving (that is, files whose names begin with @samp{#}).
        !          4912: @kbd{~} flags for deletion all files that appear to have been made as
        !          4913: backups for files that were edited (that is, files whose names end
        !          4914: with @samp{~}).
        !          4915: 
        !          4916:   @kbd{.} flags just some of the backup files for deletion: only
        !          4917: numeric backups that are not among the oldest few nor the newest few
        !          4918: backups of any one file.  Normally @code{dired-kept-versions}
        !          4919: specifies the number of newest versions of each file to keep, and
        !          4920: @code{kept-old-versions} specifies the number of oldest versions to
        !          4921: keep.  A positive numeric argument to @kbd{.} specifies the number of
        !          4922: newest versions to keep, overriding @code{dired-kept-versions}.  A
        !          4923: negative numeric argument overrides @code{kept-old-versions}, using
        !          4924: minus the value of the argument to specify the number of oldest
        !          4925: versions of each file to keep.@refill
        !          4926: 
        !          4927: 
        !          4928: @section Immediate File Operations in Dired
        !          4929: 
        !          4930:   Some file operations in Dired take place immediately when they are
        !          4931: requested.
        !          4932: 
        !          4933: @table @kbd
        !          4934: @item c
        !          4935: Copies the file described on the current line.  You must supply a file name
        !          4936: to copy to, using the minibuffer.
        !          4937: @item f
        !          4938: Visits the file described on the current line.  It is just like typing
        !          4939: @kbd{C-x C-f} and supplying that file name.  If the file on this line is a
        !          4940: subdirectory, @kbd{f} actually causes Dired to be invoked on that
        !          4941: subdirectory.  @xref{Visiting}.
        !          4942: @item o
        !          4943: Like @kbd{f}, but uses another window to display the file's buffer.  The
        !          4944: Dired buffer remains visible in the first window.  This is like using
        !          4945: @kbd{C-x 4 C-f} to visit the file.  @xref{Windows}.
        !          4946: @item r
        !          4947: Renames the file described on the current line.  You must supply a file
        !          4948: name to rename to, using the minibuffer.
        !          4949: @item v
        !          4950: Views the file described on this line using @kbd{M-x view-file}.  Viewing a
        !          4951: file is like visiting it, but is slanted toward moving around in the file
        !          4952: conveniently and does not allow changing the file.  @xref{Misc File
        !          4953: Ops,View File}.  Viewing a file that is a directory runs Dired on that
        !          4954: directory.@refill
        !          4955: @end table
        !          4956: 
        !          4957: @node Misc File Ops,, Dired, Files
        !          4958: @section Miscellaneous File Operations
        !          4959: 
        !          4960:   Emacs has commands for performing many other operations on files.
        !          4961: 
        !          4962: @findex view-file
        !          4963: @cindex viewing
        !          4964:   @kbd{M-x view-file} allows you to scan or read a file by sequential
        !          4965: screenfuls.  It reads a file name argument using the minibuffer.  After
        !          4966: reading the file into an Emacs buffer, @code{view-file} reads and displays
        !          4967: one windowful.  You can then type @key{SPC} to scroll forward one windowful,
        !          4968: or @key{DEL} to scroll backward.  Various other commands are provided for
        !          4969: moving around in the file, but none for changing it; type @kbd{C-h} while
        !          4970: viewing for a list of them.  They are mostly the same as normal Emacs
        !          4971: cursor motion commands.  To exit from viewing, type @kbd{C-c}.
        !          4972: 
        !          4973: @findex insert-file
        !          4974:   @kbd{M-x insert-file} inserts the contents of the specified file into the
        !          4975: current buffer at point, leaving point unchanged before the contents and
        !          4976: the mark after them.  @xref{Mark}.
        !          4977: 
        !          4978: @findex write-region
        !          4979: @findex append-to-file
        !          4980:   @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it copies
        !          4981: the contents of the region into the specified file.  @kbd{M-x append-to-file}
        !          4982: adds the text of the region to the end of the specified file.
        !          4983: 
        !          4984: @findex delete-file
        !          4985: @cindex deletion (of files)
        !          4986:   @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
        !          4987: command in the shell.  If you are deleting many files in one directory, it
        !          4988: may be more convenient to use Dired (@pxref{Dired}).
        !          4989: 
        !          4990: @findex rename-file
        !          4991:   @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
        !          4992: the minibuffer, then renames file @var{old} as @var{new}.  If a file named
        !          4993: @var{new} already exists, you must confirm with `yes' or renaming is not
        !          4994: done; this is because renaming causes the old meaning of the name @var{new}
        !          4995: to be lost.  If @var{old} and @var{new} are on different file systems, the
        !          4996: file @var{old} is copied and deleted.
        !          4997: 
        !          4998: @findex add-name-to-file
        !          4999:   The similar command @kbd{M-x add-name-to-file} is used to add an
        !          5000: additional name to an existing file without removing its old name.
        !          5001: The new name must belong on the same file system that the file is on.
        !          5002: 
        !          5003: @findex copy-file
        !          5004:   @kbd{M-x copy-file} reads the file @var{old} and writes a new file named
        !          5005: @var{new} with the same contents.  Confirmation is required if a file named
        !          5006: @var{new} already exists, because copying has the consequence of overwriting
        !          5007: the old contents of the file @var{new}.
        !          5008: 
        !          5009: @findex make-symbolic-link
        !          5010:   @kbd{M-x make-symbolic-link} reads two file names @var{old} and @var{linkname},
        !          5011: and then creates a symbolic link named @var{linkname} and pointing at @var{old}.
        !          5012: The effect is that future attempts to open file @var{linkname} will refer
        !          5013: to whatever file is named @var{old} at the time the opening is done, or
        !          5014: will get an error if the name @var{old} is not in use at that time.
        !          5015: Confirmation is required when creating the link if @var{linkname} is in
        !          5016: use.  Note that not all systems support symbolic links.
        !          5017: 
        !          5018: @node Buffers, Windows, Files, Top
        !          5019: @chapter Using Multiple Buffers
        !          5020: 
        !          5021: @cindex buffers
        !          5022:   The text you are editing in Emacs resides in an object called a
        !          5023: @dfn{buffer}.  Each time you visit a file, a buffer is created to hold the
        !          5024: file's text.  Each time you invoke Dired, a buffer is created to hold the
        !          5025: directory listing.  If you send a message with @kbd{C-x m}, a buffer named
        !          5026: @samp{*mail*} is used to hold the text of the message.  When you ask for a
        !          5027: command's documentation, that appears in a buffer called @samp{*Help*}.
        !          5028: 
        !          5029: @cindex selected buffer
        !          5030: @cindex current buffer
        !          5031:   At any time, one and only one buffer is @dfn{selected}.  It is also
        !          5032: called the @dfn{current buffer}.  Often we say that a command operates on
        !          5033: ``the buffer'' as if there were only one; but really this means that the
        !          5034: command operates on the selected buffer (most commands do).
        !          5035: 
        !          5036:   When Emacs makes multiple windows, each window has a chosen buffer which
        !          5037: is displayed there, but at any time only one of the windows is selected and
        !          5038: its chosen buffer is the selected buffer.  Each window's mode line displays
        !          5039: the name of the buffer that the window is displaying (@pxref{Windows}).
        !          5040: 
        !          5041:   Each buffer has a name, which can be of any length, and you can select
        !          5042: any buffer by giving its name.  Most buffers are made by visiting files,
        !          5043: and their names are derived from the files' names.  But you can also create
        !          5044: an empty buffer with any name you want.  A newly started Emacs has a buffer
        !          5045: named @samp{*scratch*} which can be used for evaluating Lisp expressions in
        !          5046: Emacs.  The distinction between upper and lower case matters in buffer
        !          5047: names.
        !          5048: 
        !          5049:   Each buffer records individually what file it is visiting, whether it is
        !          5050: modified, and what major mode and minor modes are in effect in it
        !          5051: (@pxref{Major Modes}).  Any Emacs variable can be made @dfn{local to} a
        !          5052: particular buffer, meaning its value in that buffer can be different from
        !          5053: the value in other buffers.  @xref{Locals}.
        !          5054: 
        !          5055: @menu
        !          5056: * Select Buffer::   Creating a new buffer or reselecting an old one.
        !          5057: * List Buffers::    Getting a list of buffers that exist.
        !          5058: * Misc Buffer::     Renaming; changing read-onliness; copying text.
        !          5059: * Kill Buffer::     Killing buffers you no longer need.
        !          5060: * Several Buffers:: How to go through the list of all buffers
        !          5061:                      and operate variously on several of them.
        !          5062: @end menu
        !          5063: 
        !          5064: @node Select Buffer, List Buffers, Buffers, Buffers
        !          5065: @section Creating and Selecting Buffers
        !          5066: 
        !          5067: @table @kbd
        !          5068: @item C-x b @var{buffer} @key{RET}
        !          5069: Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
        !          5070: @item C-x 4 b @var{buffer} @key{RET}
        !          5071: Similar but select a buffer named @var{buffer} in another window
        !          5072: (@code{switch-to-buffer-other-window}).
        !          5073: @end table
        !          5074: 
        !          5075: @kindex C-x 4 b
        !          5076: @findex switch-to-buffer-other-window
        !          5077: @kindex C-x b
        !          5078: @findex switch-to-buffer
        !          5079:   To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
        !          5080: @key{RET}}.  This is the command @code{switch-to-buffer} with argument
        !          5081: @var{bufname}.  Because completion is provided for buffer names, you can
        !          5082: abbreviate the buffer name (@pxref{Completion}).  An empty argument to
        !          5083: @kbd{C-x b} specifies the most recently selected buffer that is not
        !          5084: displayed in any window.@refill
        !          5085: 
        !          5086:   Most buffers are created by visiting files, or by Emacs commands that
        !          5087: want to display some text, but you can also create a buffer explicitly by
        !          5088: typing @kbd{C-x b @var{bufname} @key{RET}}.  This makes a new, empty buffer which
        !          5089: is not visiting any file, and selects it for editing.  Such buffers are
        !          5090: used for making notes to yourself.  If you try to save one, you are asked
        !          5091: for the file name to use.  The new buffer's major mode is determined by the
        !          5092: value of @code{default-major-mode} (@pxref{Major Modes}).
        !          5093: 
        !          5094:   Note that @kbd{C-x C-f}, and any other command for visiting a file, can
        !          5095: also be used to switch buffers.  @xref{Visiting}.
        !          5096: 
        !          5097: @node List Buffers, Misc Buffer, Select Buffer, Buffers
        !          5098: @section Listing Existing Buffers
        !          5099: 
        !          5100: @table @kbd
        !          5101: @item C-x C-b
        !          5102: List the existing buffers (@code{list-buffers}).
        !          5103: @end table
        !          5104: 
        !          5105: @kindex C-x C-b
        !          5106: @findex list-buffers
        !          5107:   To print a list of all the buffers that exist, type @kbd{C-x C-b}.
        !          5108: Each line in the list shows one buffer's name, major mode and visited file.
        !          5109: @samp{*} at the beginning of a line indicates the buffer is ``modified''.
        !          5110: If several buffers are modified, it may be time to save some with @kbd{C-x
        !          5111: s} (@pxref{Saving}).  @samp{%} indicates a read-only buffer.  @samp{.}
        !          5112: marks the selected buffer.  Here is an example of a buffer list:@refill
        !          5113: 
        !          5114: @smallexample
        !          5115:  MR Buffer         Size  Mode           File
        !          5116:  -- ------         ----  ----           ----
        !          5117: .*  gmacs.tex      421336 Text          /u2/emacs/man/gmacs.tex
        !          5118:     *Help*         1287  Fundamental   
        !          5119:     files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
        !          5120:   % RMAIL          64042 RMAIL          /u/rms/RMAIL
        !          5121:     emacs.tex      383402 Text          /u2/emacs/man/emacs.tex
        !          5122:  *% man            747   Dired         
        !          5123:     net.emacs      343885 Fundamental   /u/rms/net.emacs
        !          5124:     fileio.c       27691 C              /u2/emacs/src/fileio.c
        !          5125:     NEWS           67340 Text           /u2/emacs/etc/NEWS
        !          5126: @end smallexample
        !          5127: 
        !          5128: @noindent
        !          5129: Note that the buffer @samp{*Help*} was made by a help request; it is not
        !          5130: visiting any file.  The buffer @code{man} was made by Dired on the
        !          5131: directory @file{/u2/emacs/man}.
        !          5132: 
        !          5133: @node Misc Buffer, Kill Buffer, List Buffers, Buffers
        !          5134: @section Miscellaneous Buffer Operations
        !          5135: 
        !          5136: @table @kbd
        !          5137: @item C-x C-q
        !          5138: Toggle read-only status of buffer (@code{toggle-read-only}).
        !          5139: @item M-x rename-buffer
        !          5140: Change the name of the current buffer.
        !          5141: @item M-x view-buffer
        !          5142: Scroll through a buffer.
        !          5143: @end table
        !          5144: 
        !          5145: @cindex read-only buffer
        !          5146: @kindex C-x C-q
        !          5147: @findex toggle-read-only
        !          5148: @vindex buffer-read-only
        !          5149:   A buffer can be @dfn{read-only}, which means that commands to change its
        !          5150: text are not allowed.  Normally, read-only buffers are made by subsystems
        !          5151: such as Dired and Rmail that have special commands to operate on the text;
        !          5152: a read-only buffer is also made if you visit a file that is protected so
        !          5153: you cannot write it.  If you wish to make changes in a read-only buffer,
        !          5154: use the command @kbd{C-x C-q} (@code{toggle-read-only}).  It makes a
        !          5155: read-only buffer writable, and makes a writable buffer read-only.  This
        !          5156: works by setting the variable @code{buffer-read-only}, which has a local
        !          5157: value in each buffer and makes the buffer read-only if its value is
        !          5158: non-@code{nil}.
        !          5159: 
        !          5160: @findex rename-buffer
        !          5161:   @kbd{M-x rename-buffer} changes the name of the current buffer.  Specify
        !          5162: the new name as a minibuffer argument.  There is no default.  If you
        !          5163: specify a name that is in use for some other buffer, an error happens and
        !          5164: no renaming is done.
        !          5165: 
        !          5166: @findex view-buffer
        !          5167:   @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc File Ops})
        !          5168: except that it examines an already existing Emacs buffer.  View mode
        !          5169: provides commands for scrolling through the buffer conveniently but not
        !          5170: for changing it. When you exit View mode, the value of point that resulted
        !          5171: from your perusal remains in effect.
        !          5172: 
        !          5173:   The commands @kbd{C-x a} (@code{append-to-buffer}) and @kbd{M-x
        !          5174: insert-buffer} can be used to copy text from one buffer to another.
        !          5175: @xref{Accumulating Text}.@refill
        !          5176: 
        !          5177: @node Kill Buffer, Several Buffers, Misc Buffer, Buffers
        !          5178: @section Killing Buffers
        !          5179: 
        !          5180:   After you use Emacs for a while, you may accumulate a large number of
        !          5181: buffers.  You may then find it convenient to eliminate the ones you no
        !          5182: longer need.  There are several commands provided for doing this.
        !          5183: 
        !          5184: @c WideCommands
        !          5185: @table @kbd
        !          5186: @item C-x k
        !          5187: Kill a buffer, specified by name (@code{kill-buffer}).
        !          5188: @item M-x kill-some-buffers
        !          5189: Offer to kill each buffer, one by one.
        !          5190: @end table
        !          5191: 
        !          5192: @findex kill-buffer
        !          5193: @findex kill-some-buffers
        !          5194: @kindex C-x k
        !          5195: 
        !          5196:   @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you specify
        !          5197: in the minibuffer.  The default, used if you type just @key{RET} in the
        !          5198: minibuffer, is to kill the current buffer.  If the current buffer is
        !          5199: killed, another buffer is selected; a buffer that has been selected
        !          5200: recently but does not appear in any window now is chosen to be selected.
        !          5201: If the buffer being killed is modified (has unsaved editing) then you are
        !          5202: asked to confirm with `yes' before the buffer is killed.
        !          5203: 
        !          5204:   The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
        !          5205: one.  An answer of @kbd{y} means to kill the buffer.  Killing the current
        !          5206: buffer or a buffer containing unsaved changes selects a new buffer or asks
        !          5207: for confirmation just like @code{kill-buffer}.
        !          5208: 
        !          5209: @node Several Buffers,, Kill Buffer, Buffers
        !          5210: @section Operating on Several Buffers
        !          5211: @cindex buffer menu
        !          5212: 
        !          5213:   The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
        !          5214: you to request operations on various Emacs buffers by editing an Emacs
        !          5215: buffer containing a list of them.
        !          5216: 
        !          5217: @table @kbd
        !          5218: @item M-x buffer-menu
        !          5219: Begin editing a buffer listing all Emacs buffers.
        !          5220: @end table
        !          5221: 
        !          5222: @findex buffer-menu
        !          5223:   The command @code{buffer-menu} writes a list of all Emacs buffers into
        !          5224: the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
        !          5225: mode.  The buffer is read-only, and can only be changed through the special
        !          5226: commands described in this section.  Most of these commands are graphic
        !          5227: characters.  The usual Emacs cursor motion commands can be used in the
        !          5228: @samp{*Buffer List*} buffer.  The following special commands apply to the
        !          5229: buffer described on the current line.
        !          5230: 
        !          5231: @table @kbd
        !          5232: @item k
        !          5233: Request to kill the buffer.  The request shows as a @samp{K} on the
        !          5234: line, before the buffer name.  Requested kills take place when the
        !          5235: @kbd{x} command is used.
        !          5236: @item s
        !          5237: Request to save the buffer.  The request shows as an @samp{S} on the
        !          5238: line.  Requested saves take place when the @kbd{x} command is used.
        !          5239: You may request both saving and killing for one buffer.
        !          5240: @item ~
        !          5241: Mark buffer ``unmodified''.  The command @kbd{~} does this,
        !          5242: immediately when typed.
        !          5243: @item x
        !          5244: Perform previously requested kills and saves.
        !          5245: @item u
        !          5246: Remove any request made for the current line.
        !          5247: @item @key{DEL}
        !          5248: Move to previous line and remove any request made for that line.
        !          5249: @end table
        !          5250: 
        !          5251:   There are also special commands to use the buffer list to select another
        !          5252: buffer, and to specify one or more other buffers for display in additional
        !          5253: windows.
        !          5254: 
        !          5255: @table @kbd
        !          5256: @item 1
        !          5257: Select the buffer in a full-screen window.  This command takes effect
        !          5258: immediately.
        !          5259: @item 2
        !          5260: Set up two windows, with this buffer in one, and the previously
        !          5261: selected buffer (aside from the buffer @samp{*Buffer List*}) in the
        !          5262: other.
        !          5263: @item q
        !          5264: Select this buffer, and also display in other windows any buffers
        !          5265: previously flagged with the @kbd{m} command.  If there are no such
        !          5266: buffers, this command is equivalent to @kbd{1}.
        !          5267: @item m
        !          5268: Flag this buffer to be displayed in another window if the @kbd{q}
        !          5269: command is used.  The request shows as a @samp{>} at the beginning of
        !          5270: the line.  The same buffer may not have both a kill request and a
        !          5271: display request.
        !          5272: @end table
        !          5273: 
        !          5274:   All the commands that put in flags to request operations later also move
        !          5275: down a line, and accept a numeric argument as a repeat count.
        !          5276: 
        !          5277:   The command @kbd{u} cancels any request flagged for the current line, and
        !          5278: moves down; @key{DEL} does so for the previous line, and moves up to it.
        !          5279: 
        !          5280:   All that @code{buffer-menu} does directly is create and select a suitable
        !          5281: buffer, and turn on Buffer Menu mode.  Everything else described above is
        !          5282: implemented by the special commands provided in Buffer Menu mode.  One
        !          5283: consequence of this is that you can switch from the @samp{*Buffer List*}
        !          5284: buffer to another Emacs buffer, and edit there.  You can reselect the
        !          5285: @code{buffer-menu} buffer later, to perform the operations already
        !          5286: requested, or you can kill it, or pay no further attention to it.
        !          5287: 
        !          5288:   The only difference between @code{buffer-menu} and @code{list-buffers} is
        !          5289: that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and
        !          5290: @code{list-buffers} does not.  If you run @code{list-buffers} (that is,
        !          5291: type @kbd{C-x C-b}) and select the buffer list manually, you can use all of
        !          5292: the commands described here.
        !          5293: 
        !          5294: @node Windows, Major Modes, Buffers, Top
        !          5295: @chapter Multiple Windows
        !          5296: @cindex windows
        !          5297: 
        !          5298:   Emacs can split the screen into two or many windows, which can display
        !          5299: parts of different buffers, or different parts of one buffer.
        !          5300: 
        !          5301:   When multiple windows are being displayed, each window has an Emacs
        !          5302: buffer designated for display in it.  The same buffer may appear in more
        !          5303: than one window; if it does, any changes in its text are displayed in all
        !          5304: the windows where it appears.  But the windows showing the same buffer can
        !          5305: show different parts of it, because each window has its own value of point.
        !          5306: 
        !          5307: @cindex selected window
        !          5308:   At any time, one of the windows is the @dfn{selected window}; the buffer
        !          5309: this window is displaying is the current buffer.  The terminal's cursor
        !          5310: shows the location of point in this window.  Each other window has a
        !          5311: location of point as well, but since the terminal has only one cursor there
        !          5312: is no way to show where those locations are.
        !          5313: 
        !          5314:   Commands to move point affect the value of point for the selected Emacs
        !          5315: window only.  They do not change the value of point in any other Emacs
        !          5316: window, even one showing the same buffer.  The same is true for commands
        !          5317: such as @kbd{C-x b} to change the selected buffer in the selected window;
        !          5318: they do not affect other windows at all.  However, there are other commands
        !          5319: such as @kbd{C-x 4 b} that select a different window and switch buffers in
        !          5320: it.  Also, all commands that display information in a window, including
        !          5321: (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b}
        !          5322: (@code{list-buffers}), work by switching buffers in a nonselected window
        !          5323: without affecting the selected window.
        !          5324: 
        !          5325:   Each window has its own mode line, which displays the buffer name,
        !          5326: modification status and major and minor modes of the buffer that is
        !          5327: displayed in the window.  @xref{Mode Line}, for full details on the mode
        !          5328: line.
        !          5329: 
        !          5330: @c WideCommands
        !          5331: @table @kbd
        !          5332: @item C-x 2
        !          5333: Split the selected window in two, one window above the other
        !          5334: (@code{split-window-vertically}).
        !          5335: @item C-x 5
        !          5336: Split the selected window into two windows side by side
        !          5337: (@code{split-window-horizontally}).
        !          5338: @item C-x o
        !          5339: Select another window (@code{other-window}).  That is @kbd{o}, not zero.
        !          5340: @item C-x 0
        !          5341: Get rid of the selected window (@code{kill-window}).  That is a zero.
        !          5342: @item C-x 1
        !          5343: Get rid of all windows except the selected one (@code{delete-other-windows}).
        !          5344: @item C-x 4
        !          5345: Prefix key for commands to select a buffer in various ways ``in
        !          5346: another window''.
        !          5347: @item C-x ^
        !          5348: Make the selected window taller, at the expense of the other(s)
        !          5349: (@code{enlarge-window}).
        !          5350: @item C-x @}
        !          5351: Make the selected window wider (@code{enlarge-window-horizontally}).
        !          5352: @item C-M-v
        !          5353: Scroll the next window (@code{scroll-other-window}).
        !          5354: @item M-x compare-windows
        !          5355: Find next place where the text in the selected window does not match
        !          5356: the text in the next window.
        !          5357: @end table
        !          5358: 
        !          5359: @kindex C-x 2
        !          5360: @findex split-window-vertically
        !          5361:   The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
        !          5362: selected window into two windows, one above the other.  Both windows start
        !          5363: out displaying the same buffer, with the same value of point.  By default
        !          5364: the two windows each get half the height of the window that was split; a
        !          5365: numeric argument specifies how many lines to give to the top window.
        !          5366: 
        !          5367: @kindex C-x 5
        !          5368: @findex split-window-horizontally
        !          5369:   @kbd{C-x 5} (@code{split-window-horizontally}) breaks the selected
        !          5370: window into two side-by-side windows.  A numeric argument specifies
        !          5371: how many columns to give the one on the left.  A line of vertical bars
        !          5372: separates the two windows.  Windows that are not the full width of the
        !          5373: screen have mode lines, but they are truncated; also, they do not
        !          5374: always appear in inverse video, because, the Emacs display routines
        !          5375: have not been taught how to display a region of inverse video that is
        !          5376: only part of a line on the screen.
        !          5377: 
        !          5378: @vindex truncate-partial-width-windows
        !          5379:   When a window is less than the full width, text lines too long to fit are
        !          5380: frequent.  Continuing all those lines might be confusing.  The variable
        !          5381: @code{truncate-partial-width-windows} can be set non-@code{nil} to force
        !          5382: truncation in all windows less than the full width of the screen,
        !          5383: independent of the buffer being displayed and its value for
        !          5384: @code{truncate-lines}.  @xref{Continuation Lines}.@refill
        !          5385: 
        !          5386:   Horizontal scrolling is often used in side-by-side windows.
        !          5387: @xref{Display}.
        !          5388: 
        !          5389: @kindex C-x o
        !          5390: @findex other-window
        !          5391:   To select a different window, use @kbd{C-x o} (@code{other-window}).
        !          5392: That is an @kbd{o}, for `other', not a zero.  When there are more than two
        !          5393: windows, this command moves through all the windows in a cyclic order,
        !          5394: generally top to bottom and left to right.  From the rightmost and
        !          5395: bottommost window, it goes back to the one at the upper left corner.  A
        !          5396: numeric argument means to move several steps in the cyclic order of
        !          5397: windows.  A negative argument moves around the cycle in the opposite order.
        !          5398: When the minibuffer is active, the minibuffer is the last window in the
        !          5399: cycle; you can switch from the minibuffer window to one of the other
        !          5400: windows, and later switch back and finish supplying the minibuffer argument
        !          5401: that is requested.  @xref{Minibuffer Edit}.
        !          5402: 
        !          5403: @kindex C-M-v
        !          5404: @findex scroll-other-window
        !          5405:   The usual scrolling commands (@pxref{Display}) apply to the selected
        !          5406: window only, but there is one command to scroll the next window.
        !          5407: @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that @kbd{C-x o}
        !          5408: would select.  The kind of scrolling done is the same as for @kbd{C-v}.
        !          5409: 
        !          5410: @kindex C-x 0
        !          5411: @findex delete-window
        !          5412:   To delete a window, type @kbd{C-x 0} (@code{delete-window}).  The space
        !          5413: it used to occupy is distributed among the other active windows (but not
        !          5414: the minibuffer window, even if that is active at the time).  Once a window
        !          5415: is deleted, everything about it is forgotten; there is no automatic way to
        !          5416: make another window showing the same contents.
        !          5417: 
        !          5418: @kindex C-x 1
        !          5419: @findex delete-other-windows
        !          5420:   @kbd{C-x 1} (@code{delete-other-windows}) is more powerful than @kbd{C-x 0};
        !          5421: it deletes all the windows except the selected one (and the minibuffer);
        !          5422: the selected window expands to use the whole screen except for the echo
        !          5423: area.
        !          5424: 
        !          5425: @kindex C-x ^
        !          5426: @findex enlarge-window
        !          5427: @kindex C-x @}
        !          5428: @findex enlarge-window-horizontally
        !          5429: @vindex window-min-height
        !          5430: @vindex window-min-width
        !          5431:   To readjust the division of space among existing windows, use @kbd{C-x ^}
        !          5432: (@code{enlarge-window}).  It makes the currently selected window get one
        !          5433: line bigger, or as many lines as is specified with a numeric argument.
        !          5434: With a negative argument, it makes the selected window smaller.  @kbd{C-x
        !          5435: @}} (@code{enlarge-window-horizontally}) makes the selected window wider
        !          5436: by the specified number of columns.  The extra screen space given to a
        !          5437: window comes from one of its neighbors, if that is possible; otherwise, all
        !          5438: the competing windows are shrunk in the same proportion.  If this makes any
        !          5439: windows too small, those windows are deleted and their space is divided up.
        !          5440: The minimum size is specified by the variables @code{window-min-height} and
        !          5441: @code{window-min-width}.
        !          5442: 
        !          5443: @findex compare-windows
        !          5444:   The command @kbd{M-x compare-windows} compares the text in the current
        !          5445: window with that in the next window (the one @kbd{C-M-v} would scroll).
        !          5446: Comparison starts at point in each window.  Point moves forward in each
        !          5447: window, a character at a time in each window, until the next characters
        !          5448: in the two windows are different.  Then the command is finished.
        !          5449: 
        !          5450: @kindex C-x 4
        !          5451:   @kbd{C-x 4} is a prefix key for commands that select another window
        !          5452: (splitting the window if there is only one) and select a buffer in that
        !          5453: window.  Different @kbd{C-x 4} commands have different ways of finding the
        !          5454: buffer to select.
        !          5455: 
        !          5456: @findex switch-to-buffer-other-window
        !          5457: @findex find-file-other-window
        !          5458: @findex find-tag-other-window
        !          5459: @findex dired-other-window
        !          5460: @findex mail-other-window
        !          5461: @table @kbd
        !          5462: @item C-x 4 b @var{bufname} @key{RET}
        !          5463: Select buffer @var{bufname} in another window.  This runs
        !          5464: @code{switch-to-buffer-other-window}.
        !          5465: @item C-x 4 f @var{filename} @key{RET}
        !          5466: Visit file @var{filename} and select its buffer in another window.  This
        !          5467: runs @code{find-file-other-window}.  @xref{Visiting}.
        !          5468: @item C-x 4 d @var{directory} @key{RET}
        !          5469: Select a Dired buffer for directory @var{directory} in another window.
        !          5470: This runs @code{dired-other-window}.  @xref{Dired}.
        !          5471: @item C-x 4 m
        !          5472: Start composing a mail message in another window.  This runs
        !          5473: @code{mail-other-window}, and its same-window version is @kbd{C-x m}
        !          5474: (@pxref{Sending Mail}).
        !          5475: @item C-x 4 .
        !          5476: Find a tag in the current tag table in another window.  This runs
        !          5477: @code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
        !          5478: (@pxref{Tags}).
        !          5479: @end table
        !          5480: 
        !          5481: @node Major Modes, Indentation, Windows, Top
        !          5482: @chapter Major Modes
        !          5483: @cindex major modes
        !          5484: @kindex TAB
        !          5485: @kindex DEL
        !          5486: @kindex LFD
        !          5487: 
        !          5488:   Emacs has many different @dfn{major modes}, each of which customizes
        !          5489: Emacs for editing text of a particular sort.  The major modes are mutually
        !          5490: exclusive, and each buffer has one major mode at any time.  The mode line
        !          5491: normally contains the name of the current major mode, in parentheses.
        !          5492: @xref{Mode Line}.
        !          5493: 
        !          5494:   The least specialized major mode is called @dfn{Fundamental mode}.  This
        !          5495: mode has no mode-specific redefinitions or variable settings, so that each
        !          5496: Emacs command behaves in its most general manner, and each option is in its
        !          5497: default state.  For editing any specific type of text, such as Lisp code or
        !          5498: English text, you should switch to the appropriate major mode, such as Lisp
        !          5499: mode or Text mode.
        !          5500: 
        !          5501:   Selecting a major mode changes the meanings of a few keys to become more
        !          5502: specifically adapted to the language being edited.  The ones which are
        !          5503: changed frequently are @key{TAB}, @key{DEL}, and @key{LFD}.  In addition,
        !          5504: the commands which handle comments use the mode to determine how comments
        !          5505: are to be delimited.  Many major modes redefine the syntactical properties
        !          5506: of characters appearing in the buffer.  @xref{Syntax}.
        !          5507: 
        !          5508:   The major modes fall into three major groups.  Lisp mode (which has
        !          5509: several variants), C mode and Muddle mode are for specific programming
        !          5510: languages.  Text mode, Nroff mode, @TeX{} mode and outline mode are for
        !          5511: editing English text.  The remaining major modes are not intended for use
        !          5512: on user's files; they are used in buffers created for specific purposes by
        !          5513: Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), and
        !          5514: Mail mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), and Shell
        !          5515: mode for buffers used for communicating with an inferior shell process
        !          5516: (@pxref{Shell}).
        !          5517: 
        !          5518:   Selecting a new major mode is done with an @kbd{M-x} command.  From the
        !          5519: name of a major mode, add @code{-mode} to get the name of a command
        !          5520: function to select that mode.  Thus, you can enter Lisp mode by executing
        !          5521: @kbd{M-x lisp-mode}.
        !          5522: 
        !          5523: @vindex auto-mode-alist
        !          5524:   When you visit a file, Emacs usually chooses the right major mode based
        !          5525: on the file's name.  For example, files whose names end in @code{.c} are
        !          5526: edited in C mode.  The correspondence between file names and major mode is
        !          5527: controlled by the variable @code{auto-mode-alist}.  Its value is a list in
        !          5528: which each element has the form
        !          5529: 
        !          5530: @example
        !          5531: (@var{regexp} . @var{mode-function})
        !          5532: @end example
        !          5533: 
        !          5534: @noindent
        !          5535: For example, one element normally found in the list has the form
        !          5536: @code{(@t{"\\.c$"} . c-mode)}, and it is responsible for selecting C mode
        !          5537: for files whose names end in @code{.c}.  (Note that @samp{\\} is needed in
        !          5538: Lisp syntax to include a @samp{\} in the string.)
        !          5539: 
        !          5540:   You can specify which major mode should be used for editing a certain
        !          5541: file by a special sort of text in the first nonblank line of the file.  The
        !          5542: mode name should appear in this line both preceded and followed by
        !          5543: @samp{-*-}.  Other text may appear on the line as well.  For example,
        !          5544: 
        !          5545: @example
        !          5546: ;-*-Lisp-*-
        !          5547: @end example
        !          5548: 
        !          5549: @noindent
        !          5550: tells Emacs to use Lisp mode.  Note how the semicolon is used to make Lisp
        !          5551: treat this line as a comment.  Such an explicit specification overrides any
        !          5552: defaulting based on the file name.
        !          5553: 
        !          5554:   Another format of mode specification is
        !          5555: 
        !          5556: @example
        !          5557: -*-Mode: @var{modename};-*-
        !          5558: @end example
        !          5559: 
        !          5560: @noindent
        !          5561: which allows other things besides the major mode name to be specified.
        !          5562: However, Emacs does not look for anything except the mode name.
        !          5563: 
        !          5564: @vindex default-major-mode
        !          5565:   When a file is visited that does not specify a major mode to use, or when
        !          5566: a new buffer is created with @kbd{C-x b}, the major mode used is that
        !          5567: specified by the variable @code{default-major-mode}.  Normally this value
        !          5568: is the symbol @code{fundamental-mode}, which specifies Fundamental mode.
        !          5569: If @code{default-major-mode} is @code{nil}, the major mode is taken from
        !          5570: the previously selected buffer.
        !          5571: 
        !          5572:   Most programming language major modes specify that only blank lines
        !          5573: separate paragraphs.  This is so that the paragraph commands remain useful.
        !          5574: @xref{Paragraphs}.  They also cause Auto Fill mode to use the definition of
        !          5575: @key{TAB} to indent the new lines it creates.  This is because most lines
        !          5576: in a program are usually indented.  @xref{Indentation}.
        !          5577: 
        !          5578: @node Indentation, Text, Major Modes, Top
        !          5579: @chapter Indentation
        !          5580: @cindex indentation
        !          5581: 
        !          5582: @c WideCommands
        !          5583: @table @kbd
        !          5584: @item @key{TAB}
        !          5585: Indent current line ``appropriately'' in a mode-dependent fashion.
        !          5586: @item @key{LFD}
        !          5587: Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
        !          5588: @item M-^
        !          5589: Merge two lines (@code{delete-indentation}).  This would cancel out
        !          5590: the effect of @key{LFD}.
        !          5591: @item C-M-o
        !          5592: Split line at point; text on the line after point becomes a new line
        !          5593: indented to the same column that it now starts in (@code{split-line}).
        !          5594: @item M-m
        !          5595: Move (forward or back) to the first nonblank character on the current
        !          5596: line (@code{back-to-indentation}).
        !          5597: @item C-M-\
        !          5598: Indent several lines to same column (@code{indent-region}).
        !          5599: @item C-x @key{TAB}
        !          5600: Shift block of lines rigidly right or left (@code{indent-rigidly}).
        !          5601: @item M-i
        !          5602: Indent from point to the next prespecified tab stop column
        !          5603: (@code{tab-to-tab-stop}).
        !          5604: @item M-x indent-relative
        !          5605: Indent from point to under an indentation point in the previous line.
        !          5606: @end table
        !          5607: 
        !          5608: @kindex TAB
        !          5609: @cindex indentation
        !          5610:   Most programming languages have some indentation convention.  For Lisp
        !          5611: code, lines are indented according to their nesting in parentheses.  The
        !          5612: same general idea is used for C code, though many details are different.
        !          5613: 
        !          5614:   Whatever the language, to indent a line, use the @key{TAB} command.  Each
        !          5615: major mode defines this command to perform the sort of indentation
        !          5616: appropriate for the particular language.  In Lisp mode, @key{TAB} aligns
        !          5617: the line according to its depth in parentheses.  No matter where in the
        !          5618: line you are when you type @key{TAB}, it aligns the line as a whole.  In C
        !          5619: mode, @key{TAB} implements a subtle and sophisticated indentation style that
        !          5620: knows about many aspects of C syntax.
        !          5621: 
        !          5622: @kindex TAB
        !          5623: @kindex LFD
        !          5624: @findex indent-new-line
        !          5625:   In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
        !          5626: indents to the next tab stop column.  You can set the tab stops with
        !          5627: @kbd{M-x edit-tab-stops}.
        !          5628: 
        !          5629: @menu
        !          5630: * Indentation Commands:: Various commands and techniques for indentation.
        !          5631: * Tab Stops::            You can set arbitrary "tab stops" and then
        !          5632:                          indent to the next tab stop when you want to.
        !          5633: * Just Spaces::          You can request indentation using just spaces.
        !          5634: @end menu
        !          5635: 
        !          5636: @node Indentation Commands,, Indentation, Indentation
        !          5637: @section Indentation Commands and Techniques
        !          5638: @c ??? Explain what Emacs has instead of space-indent-flag.
        !          5639: 
        !          5640:   If you just want to insert a tab character in the buffer, you can type
        !          5641: @kbd{C-q @key{TAB}}.
        !          5642: 
        !          5643: @kindex M-m
        !          5644: @findex back-to-indentation
        !          5645:   To move over the indentation on a line, do @kbd{Meta-m}
        !          5646: (@code{back-to-indentation}).  This command, given anywhere on a line,
        !          5647: positions point at the first nonblank character on the line.
        !          5648: 
        !          5649:   To insert an indented line before the current line, do @kbd{C-a C-o
        !          5650: @key{TAB}}.  To make an indented line after the current line, use @kbd{C-e
        !          5651: @key{LFD}}.
        !          5652: 
        !          5653: @kindex C-M-o
        !          5654: @findex split-line
        !          5655:   @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
        !          5656: the line vertically down, so that the current line becomes two lines.
        !          5657: @kbd{C-M-o} first moves point forward over any spaces and tabs.  Then it
        !          5658: inserts after point a newline and enough indentation to reach the same
        !          5659: column point is on.  Point remains before the inserted newline; in this
        !          5660: regard, @kbd{C-M-o} resembles @kbd{C-o}.
        !          5661: 
        !          5662: @kindex M-\
        !          5663: @kindex M-^
        !          5664: @findex delete-horizontal-space
        !          5665: @findex delete-indentation
        !          5666:   To join two lines cleanly, use the @kbd{Meta-^} (@code{delete-indentation})
        !          5667: command to delete the indentation at the front of the current line, and the
        !          5668: line boundary as well.  They are replaced by a single space, or by no space
        !          5669: if at the beginning of a line or before a @samp{)} or after a @samp{(}.  To
        !          5670: delete just the indentation of a line, go to the beginning of the line and
        !          5671: use @kbd{Meta-\} (@code{delete-horizontal-space}), which deletes all spaces
        !          5672: and tabs around the cursor.
        !          5673: 
        !          5674: @kindex C-M-\
        !          5675: @kindex C-x TAB
        !          5676: @findex indent-region
        !          5677: @findex indent-rigidly
        !          5678:   There are also commands for changing the indentation of several lines at
        !          5679: once.  @kbd{Control-Meta-\} (@code{indent-region}) gives each line which
        !          5680: begins in the region the ``usual'' indentation by invoking @key{TAB} at the
        !          5681: beginning of the line.  A numeric argument specifies the column to indent
        !          5682: to, and each line is shifted left or right so that its first nonblank
        !          5683: character appears in that column.  @kbd{C-x @key{TAB}}
        !          5684: (@code{indent-rigidly}) moves all of the lines in the region right by its
        !          5685: argument (left, for negative arguments).  The whole group of lines moves
        !          5686: rigidly sideways, which is how the command gets its name.@refill
        !          5687: 
        !          5688: @findex indent-relative
        !          5689:   @kbd{M-x indent-relative} indents at point based on the previous line
        !          5690: (actually, the last nonempty line.)  It inserts whitespace at point, moving
        !          5691: point, until it is underneath an indentation point in the previous line.
        !          5692: An indentation point is the end of a sequence of whitespace or the end of
        !          5693: the line.  If point is farther right than any indentation point in the
        !          5694: previous line, the whitespace before point is deleted and the first
        !          5695: indentation point then applicable is used.  If no indentation point is
        !          5696: applicable even then, @code{tab-to-tab-stop} is run.
        !          5697: 
        !          5698:   @code{indent-relative} is the definition of @key{TAB} in Indented Text
        !          5699: mode.  @xref{Text}.
        !          5700: 
        !          5701: @node Tab Stops, Just Spaces, Indentation Commands, Indentation
        !          5702: @section Tab Stops
        !          5703: 
        !          5704: @kindex M-i
        !          5705: @findex tab-to-tab-stop
        !          5706:   For typing in tables, you can use Text mode's definition of @key{TAB},
        !          5707: @code{tab-to-tab-stop}.  This command inserts indentation before point,
        !          5708: enough to reach the next tab stop column.  If you are not in Text mode,
        !          5709: this function can be found on @kbd{M-i} anyway.
        !          5710: 
        !          5711: @findex edit-tab-stops
        !          5712: @findex edit-tab-stops-note-changes
        !          5713: @kindex C-x C-s
        !          5714: @vindex tab-stop-list
        !          5715:   The tab stops used by @kbd{M-i} can be set arbitrarily by the user.
        !          5716: They are stored in a variable called @code{tab-stop-list}, as a list of
        !          5717: column-numbers in increasing order.
        !          5718: 
        !          5719:   The convenient way to set the tab stops using @kbd{M-x edit-tab-stops},
        !          5720: which creates and selects a buffer containing a description of the tab stop
        !          5721: settings.  You can edit this buffer to specify different tab stops, and
        !          5722: then type @kbd{C-x C-s} to make those new tab stops take effect.  In the
        !          5723: tab stop buffer, @kbd{C-x C-s} runs the function
        !          5724: @code{edit-tab-stops-note-changes} rather than its usual definition
        !          5725: @code{save-buffer}.  @code{edit-tab-stops} records which buffer was current
        !          5726: when you invoked it, and stores the tab stops back in that buffer; normally
        !          5727: all buffers share the same tab stops and changing them in one buffer
        !          5728: affects all, but if you happen to make @code{tab-stop-list} local in one
        !          5729: buffer then @code{edit-tab-stops} in that buffer will edit the local
        !          5730: settings.
        !          5731: 
        !          5732:   Here is what the text representing the tab stops looks like for ordinary
        !          5733: tab stops every eight columns.
        !          5734: 
        !          5735: @example
        !          5736:         :       :       :       :       :       :
        !          5737: 0         1         2         3         4        
        !          5738: 0123456789012345678901234567890123456789012345678
        !          5739: To install changes, type C-x C-s
        !          5740: @end example
        !          5741: 
        !          5742:   The first line contains a colon at each tab stop.  The remaining lines
        !          5743: are present just to help you see where the colons are and know what to do.
        !          5744: 
        !          5745:   Note that the tab stops that control @code{tab-to-tab-stop} have nothing
        !          5746: to do with displaying tab characters in the buffer.  @xref{Display Vars},
        !          5747: for more information on that.
        !          5748: 
        !          5749: @node Just Spaces,, Tab Stops, Indentation
        !          5750: @section Tabs vs. Spaces
        !          5751: 
        !          5752: @vindex indent-tabs-mode
        !          5753:   Emacs normally uses both tabs and spaces to indent lines.  If you prefer,
        !          5754: all indentation can be made from spaces only.  To request this, set
        !          5755: @code{indent-tabs-mode} to @code{nil}.
        !          5756: 
        !          5757: @findex tabify
        !          5758: @findex untabify
        !          5759:   There are also commands to convert tabs to spaces or vice versa, always
        !          5760: preserving the columns of all nonblank text.  @kbd{M-x tabify} scans the
        !          5761: region for sequences of spaces, and converts sequences of at least three
        !          5762: spaces to tabs if that can be done without changing indentation.  @kbd{M-x
        !          5763: untabify} changes all tabs in the region to appropriate numbers of spaces.
        !          5764: 
        !          5765: @node Text, Programs, Indentation, Top
        !          5766: @chapter Commands for Human Languages
        !          5767: @cindex text
        !          5768: 
        !          5769:   The term @dfn{text} has two widespread meanings in our area of the
        !          5770: computer field.  One is data that is a sequence of characters.  Any file
        !          5771: that you edit with Emacs is text, in this sense of the word.  The other
        !          5772: meaning is more restrictive; it is, a sequence of characters in a human
        !          5773: language for humans to read (possibly after processing by a text
        !          5774: formatter), as opposed to a program or commands for a program.
        !          5775: 
        !          5776:   Human languages have syntactic/stylistic conventions that can be
        !          5777: supported or used to advantage by editor commands: conventions involving
        !          5778: words, sentences, paragraphs, and capital letters.  This chapter describes
        !          5779: Emacs commands for all of these things.  There are also commands for
        !          5780: @dfn{filling}, or rearranging paragraphs into lines of approximately equal
        !          5781: length.
        !          5782: 
        !          5783:   The commands for moving over and killing words (@pxref{Words}), sentences
        !          5784: (@pxref{Sentences}) and paragraphs (@pxref{Paragraphs}) are are primarily
        !          5785: intended for human-language text, but are very often useful in editing
        !          5786: programs also.
        !          5787: 
        !          5788:   Emacs has several major modes for editing human language text.
        !          5789: If the file contains text pure and simple, use Text mode, which customizes
        !          5790: Emacs in small ways for the syntactic conventions of text.  For text which
        !          5791: contains embedded commands for text formatters, Emacs has other major modes,
        !          5792: each for a particular text formatter.  Thus, for input to @TeX{}, you would
        !          5793: use @TeX{} mode; for input to nroff, Nroff mode.
        !          5794: 
        !          5795: @menu
        !          5796: * Text Mode::   The major modes for editing text files.
        !          5797: * Nroff Mode::  The major mode for editing input to the formatter nroff.
        !          5798: * TeX Mode::    The major mode for editing input to the formatter TeX.
        !          5799: * Outline Mode::The major mode for editing outlines.
        !          5800: * Words::       Moving over and killing words.
        !          5801: * Sentences::   Moving over and killing sentences.
        !          5802: * Paragraphs:: Moving over paragraphs.
        !          5803: * Pages::      Moving over pages.
        !          5804: * Filling::     Filling or justifying text
        !          5805: * Case::        Changing the case of text
        !          5806: @end menu
        !          5807: 
        !          5808: @node Text Mode, Words, Text, Text
        !          5809: @section Text Mode
        !          5810: 
        !          5811: @findex tab-to-tab-stop
        !          5812: @findex edit-tab-stops
        !          5813: @cindex Text mode
        !          5814: @kindex TAB
        !          5815: @findex text-mode
        !          5816:   Editing files of text in a human language ought to be done using Text
        !          5817: mode rather than Lisp or Fundamental mode.  Invoke @kbd{M-x text-mode} to
        !          5818: enter Text mode.  In Text mode, @key{TAB} runs the function
        !          5819: @code{tab-to-tab-stop}, which allows you to use arbitrary tab stops set
        !          5820: with @kbd{M-x edit-tab-stops} (@pxref{Tab Stops}).  Features concerned with
        !          5821: comments in programs are turned off except when explicitly invoked.  The
        !          5822: syntax table is changed so that periods are not considered part of a word,
        !          5823: while apostrophes, backspaces and underlines are.
        !          5824: 
        !          5825: @findex indented-text-mode
        !          5826:   A similar variant mode is Indented Text mode, intended for editing text
        !          5827: in which most lines are indented.  This mode defines @key{TAB} to run
        !          5828: @code{indent-relative} (@pxref{Indentation}), and makes Auto Fill indent
        !          5829: the lines it creates.  The result is that normally a line made by Auto
        !          5830: Filling, or by @key{LFD}, is indented just like the previous line.  Use
        !          5831: @kbd{M-x indented-text-mode} to select this mode.
        !          5832: 
        !          5833: @vindex text-mode-hook
        !          5834:   Entering Text mode or Indented Text mode calls with no arguments the
        !          5835: value of the variable @code{text-mode-hook}, if that value exists and is
        !          5836: not @code{nil}.  This value is also called when modes related to Text mode
        !          5837: are entered; this includes Nroff mode, @TeX{} mode, Outline mode and Mail
        !          5838: mode.  Your hook can look at the value of @code{major-mode} to see which of
        !          5839: these modes is actually being entered.
        !          5840: 
        !          5841: @menu
        !          5842:   Two modes similar to Text mode are of use for editing text that is to
        !          5843: be passed through a text formatter before achieving the form in which
        !          5844: humans are to read it.
        !          5845: 
        !          5846: * Nroff Mode::  The major mode for editing input to the formatter nroff.
        !          5847: * TeX Mode::    The major mode for editing input to the formatter TeX.
        !          5848: 
        !          5849:   Another similar mode is used for editing outlines.  It allows you
        !          5850: to view the text at various levels of detail.  You can view either
        !          5851: the outline headings alone or both headings and text; you can also
        !          5852: hide some of the headings at lower levels from view to make the high
        !          5853: level structure more visible.
        !          5854: 
        !          5855: * Outline Mode::The major mode for editing outlines.
        !          5856: @end menu
        !          5857: 
        !          5858: @node Nroff Mode, TeX Mode, Text Mode, Text Mode
        !          5859: @subsection Nroff Mode
        !          5860: 
        !          5861: @findex nroff-mode
        !          5862:   Nroff mode is a mode like Text mode but modified to handle nroff commands
        !          5863: present in the text.  Invoke @kbd{M-x nroff-mode} to enter this mode.  It
        !          5864: differs from Text mode in only a few ways.  All nroff command lines are
        !          5865: considered paragraph separators, so that filling will never garble the
        !          5866: nroff commands.  Pages are separated by @samp{.bp} commands.  Also, three
        !          5867: special commands are provided that are not in Text mode:
        !          5868: 
        !          5869: @findex forward-text-line
        !          5870: @findex backward-text-line
        !          5871: @findex count-text-lines
        !          5872: @kindex M-n
        !          5873: @kindex M-p
        !          5874: @kindex M-?
        !          5875: @table @kbd
        !          5876: @item M-n
        !          5877: Move to the beginning of the next line that isn't an nroff command
        !          5878: (@code{forward-text-line}).  An argument is a repeat count.
        !          5879: @item M-p
        !          5880: Like @kbd{M-n} but move up (@code{backward-text-line}).
        !          5881: @item M-?
        !          5882: Prints in the echo area the number of text lines (lines that are not
        !          5883: nroff commands) in the region (@code{count-text-lines}).
        !          5884: @end table
        !          5885: 
        !          5886: @findex electric-nroff-mode
        !          5887:   The other feature of Nroff mode is that you can turn on Electric
        !          5888: Nroff newline mode.  This is a minor mode that you can turn on or off
        !          5889: with @kbd{M-x electric-nroff-mode} (@pxref{Minor Modes}).  When the
        !          5890: mode is on, each time you use @key{RET} to end a line that contains
        !          5891: an nroff command that opens a kind of grouping, the matching
        !          5892: nroff command to close that grouping is automatically inserted on
        !          5893: the following line.  For example, if you are at the beginning of
        !          5894: a line and type @kbd{.@: ( b @key{RET}}, the matching command
        !          5895: @samp{.)b} will be inserted on a new line following point.
        !          5896: 
        !          5897: @vindex nroff-mode-hook
        !          5898:   Entering Nroff mode calls with no arguments the value of the variable
        !          5899: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
        !          5900: does the same with the variable @code{nroff-mode-hook}.
        !          5901: 
        !          5902: @node TeX Mode, Outline Mode, Nroff Mode, Text Mode
        !          5903: @subsection @TeX{} Mode
        !          5904: @cindex TeX
        !          5905: @cindex LaTeX
        !          5906: @findex TeX-mode
        !          5907: @findex tex-mode
        !          5908: 
        !          5909:   @TeX{} is an extremely powerful text formatter written by Donald Knuth;
        !          5910: it is also free, like GNU Emacs.  La@TeX{} is a simplified input format for
        !          5911: @TeX{}, implemented by @TeX{} macros.  It comes with @TeX{}.@refill
        !          5912: 
        !          5913:   @TeX{} mode is designed for editing files of input for plain @TeX{} or La@TeX{}.
        !          5914: It provides facilities for checking the balance of delimiters and for
        !          5915: invoking @TeX{} on all or part of the file.  Type @kbd{M-x tex-mode} to
        !          5916: enter @TeX{} mode.
        !          5917: 
        !          5918: @table @kbd
        !          5919: @item "
        !          5920: Insert @samp{@`@`}, @samp{"} or @samp{@'@'} according to context (@code{TeX-insert-quote}).
        !          5921: @item @key{LFD}
        !          5922: Insert a paragraph break (two newlines) and check the previous
        !          5923: paragraph for unbalanced braces or dollar signs
        !          5924: (@code{TeX-terminate-paragraph}).
        !          5925: @item M-x validate-TeX-buffer
        !          5926: Check each paragraph in the buffer for unbalanced braces or dollar signs.
        !          5927: @item M-@{
        !          5928: Insert @samp{@{@}} and position point between them (@code{TeX-insert-braces}).
        !          5929: @item M-@}
        !          5930: Move forward past the next unmatched close brace (@code{up-list}).
        !          5931: @item C-c C-r
        !          5932: Invoke @TeX{} on the current region, plus the buffer's header
        !          5933: (@code{TeX-region}).
        !          5934: @item C-c C-b
        !          5935: Invoke @TeX{} on the entire current buffer (@code{TeX-buffer}).
        !          5936: @item C-c C-p
        !          5937: Print the output from the last @kbd{C-c C-r} or @kbd{C-c C-b} command
        !          5938: (@code{TeX-print}).
        !          5939: @end table
        !          5940: 
        !          5941: @findex TeX-insert-quote
        !          5942: @kindex " (TeX mode)
        !          5943:   In @TeX{}, the character @samp{"} is not normally used; one uses @samp{``}
        !          5944: to start a quotation and @samp{''} to end one.  @TeX{} mode defines the key
        !          5945: @kbd{"} to insert @samp{``} after whitespace or an open brace, @samp{"}
        !          5946: after a backslash, or @samp{''} otherwise.  This is done by the command
        !          5947: @code{TeX-insert-quote}.  If you need the character @samp{"} itself in
        !          5948: unusual contexts, use @kbd{C-q} to insert it.  Also, @kbd{"} with a
        !          5949: numeric argument always inserts that number of @samp{"} characters.
        !          5950: 
        !          5951:   In @TeX{} mode, @samp{$} has a special syntax code which attempts to
        !          5952: understand the way @TeX{} math mode delimiters match.  When you insert a
        !          5953: @samp{$} that is meant to exit math mode, the position of the matching
        !          5954: @samp{$} that entered math mode is displayed for a second.  This is the
        !          5955: same feature that displays the open brace that matches a close brace that
        !          5956: is inserted.  However, there is no way to tell whether a @samp{$} enters
        !          5957: math mode or leaves it; so when you insert a @samp{$} that enters math
        !          5958: mode, the previous @samp{$} position is shown as if it were a match, even
        !          5959: though they are actually unrelated.
        !          5960: 
        !          5961: @findex TeX-insert-braces
        !          5962: @kindex M-@{
        !          5963: @findex up-list
        !          5964: @kindex M-@}
        !          5965:   If you prefer to keep braces balanced at all times, you can use @kbd{M-@{}
        !          5966: (@code{TeX-insert-braces}) to insert a pair of braces.  It leaves point
        !          5967: between the two braces so you can insert the text that belongs inside.
        !          5968: Afterward, use the command @kbd{M-@}} (@code{up-list}) to move forward
        !          5969: past the close brace.
        !          5970: 
        !          5971: @findex validate-TeX-buffer
        !          5972: @findex TeX-terminate-paragraph
        !          5973: @kindex LFD (TeX mode)
        !          5974:   There are two commands for checking the matching of braces.  @key{LFD}
        !          5975: (@code{TeX-terminate-paragraph}) checks the paragraph before point, and
        !          5976: inserts two newlines to start a new paragraph.  It prints a message in the
        !          5977: echo area if any mismatch is found.  @kbd{M-x validate-TeX-buffer} checks
        !          5978: the entire buffer, paragraph by paragraph.  When it finds a paragraph that
        !          5979: contains a mismatch, it displays point at the beginning of the paragraph
        !          5980: for a few seconds and pushes a mark at that spot.  Scanning continues
        !          5981: until the whole buffer has been checked or until you type another key.
        !          5982: The positions of the last several paragraphs with mismatches can be
        !          5983: found in the mark ring (@pxref{Mark Ring}).
        !          5984:   
        !          5985: Note that square brackets and parentheses are matched in @TeX{} mode, not
        !          5986: just braces.  This is wrong for the purpose of checking @TeX{} syntax.
        !          5987: However, parentheses and square brackets are likely to be used in text as
        !          5988: matching delimiters and it is useful for the various motion commands and
        !          5989: automatic match display to work with them.
        !          5990: 
        !          5991: @findex TeX-buffer
        !          5992: @kindex C-c C-b
        !          5993: @findex TeX-print
        !          5994: @kindex C-c C-p
        !          5995:   You can pass the current buffer through an inferior @TeX{} by means of
        !          5996: @kbd{C-c C-b} (@code{TeX-buffer}).  The error messages appear in a buffer
        !          5997: called @samp{*TeX-shell*}.  The formatted output appears in a file in
        !          5998: @file{/tmp}; to print it, type @kbd{C-c C-p} (@code{TeX-print}).@refill
        !          5999: 
        !          6000: @findex TeX-region
        !          6001: @kindex C-c C-r
        !          6002:   You can also pass an arbitrary region through an inferior @TeX{} by typing
        !          6003: @kbd{C-c C-r} (@code{TeX-region}).  This is tricky, however, because most files
        !          6004: of @TeX{} input contain commands at the beginning to set paramaters and
        !          6005: define macros, without which no later part of the file will format
        !          6006: correctly.  To solve this problem, @kbd{C-c C-r} allows you to designate a
        !          6007: part of the file as containing essential commands; it is included before
        !          6008: the specified region as part of the input to @TeX{}.  The designated part
        !          6009: of the file is called the @dfn{header}.
        !          6010: 
        !          6011: @cindex header (TeX mode)
        !          6012:   To indicate the bounds of the header, insert two special strings in the
        !          6013: file.  Insert @samp{%**start of header} before the header, and @samp{%**end of
        !          6014: header} after it.  Each string must appear entirely on one line, but there
        !          6015: may be other text on the line before or after.  The lines containing the
        !          6016: two strings are not included in the header.
        !          6017: 
        !          6018:   If @samp{%**start of header} does not appear within the first ten lines of
        !          6019: the text in the buffer, @kbd{C-c C-r} assumes that there is no header.
        !          6020: 
        !          6021: @vindex TeX-mode-hook
        !          6022:   Entering @TeX{} mode calls with no arguments the value of the variable
        !          6023: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
        !          6024: does the same with the variable @code{TeX-mode-hook}.
        !          6025: 
        !          6026:   @TeX{} for Berkeley Unix can be obtained on a 1600bpi tar tape for a $75
        !          6027: distribution fee from
        !          6028: 
        !          6029: @display
        !          6030: Pierre MacKay
        !          6031: Department of Computer Science, FR-35
        !          6032: University of Washington
        !          6033: Seattle, WA 98195
        !          6034: @end display
        !          6035: 
        !          6036: @noindent
        !          6037: It would work on system V as well if that version of Unix had a reasonable
        !          6038: Pascal compiler.  Outside the U.S., add $10 to cover extra costs.
        !          6039: 
        !          6040: @node Outline Mode,, TeX Mode, Text Mode
        !          6041: @subsection Outline Mode
        !          6042: @cindex outlines
        !          6043: @cindex selective display
        !          6044: @cindex invisible lines
        !          6045: 
        !          6046:   Outline mode is a major mode much like Text mode but intended for editing
        !          6047: outlines.  It allows you to make parts of the text temporarily invisible
        !          6048: to that you can see just the overall structure of the outline.  Type
        !          6049: @kbd{M-x outline-mode} to turn on Outline mode in the current buffer.
        !          6050: 
        !          6051:   When a line is invisible in outline mode, it does not appear on the
        !          6052: screen in any form.  The screen appears exactly as if the invisible line
        !          6053: were deleted.  All editing commands treat the text of the invisible line as
        !          6054: part of the previous visible line.  For example, @kbd{C-n} moves onto the
        !          6055: next visible line.  Killing an entire visible line, including its
        !          6056: terminating newline, really kills all the following invisible lines along
        !          6057: with it; yanking it all back yanks the invisible lines and they remain
        !          6058: invisible.
        !          6059: 
        !          6060: @cindex heading lines (Outline mode)
        !          6061: @cindex body lines (Outline mode)
        !          6062:   Outline mode assumes that the lines in the buffer are of two types:
        !          6063: @dfn{heading lines} and @dfn{body lines}.  A heading line represents a topic in the
        !          6064: outline.  Heading lines start with one or more stars; the number of stars
        !          6065: determines the depth of the heading in the outline structure.  Thus, a
        !          6066: heading line with one star is a major topic; all the heading lines with
        !          6067: two stars between it and the next one-star heading are its subtopics; and
        !          6068: so on.  Any line that is not a heading line is a body line.  Body lines
        !          6069: belong to the preceding heading line.  Here is an example:
        !          6070: 
        !          6071: @example
        !          6072: * Food
        !          6073: 
        !          6074: This is the body,
        !          6075: which says something about the topic of food.
        !          6076: 
        !          6077: ** Delicious Food
        !          6078: 
        !          6079: This is the body of the second-level header.
        !          6080: 
        !          6081: ** Distasteful Food
        !          6082: 
        !          6083: This could have
        !          6084: a body too, with
        !          6085: several lines.
        !          6086: 
        !          6087: *** Dormitory Food
        !          6088: 
        !          6089: * Shelter
        !          6090: 
        !          6091: A second first-level topic with its header line.
        !          6092: @end example
        !          6093: 
        !          6094: 
        !          6095:   A heading line together with all following body lines are called
        !          6096: collectively an @dfn{entry}.  A heading line together with all following
        !          6097: deeper heading lines and their body lines is called a @dfn{subtree}.
        !          6098: 
        !          6099: @table @kbd
        !          6100: @item M-@}
        !          6101: Move point to the next visible heading line (@code{next-visible-heading}).
        !          6102: @item M-@{
        !          6103: Move point to the previous visible heading line
        !          6104: (@code{previous-visible-heading}).
        !          6105: @item M-x hide-body
        !          6106: Make all body lines in the buffer invisible.
        !          6107: @item M-x show-all
        !          6108: Make all lines in the buffer visible.
        !          6109: @item C-c C-h
        !          6110: Make everything under this heading invisible, but not this heading itself
        !          6111: (@code{hide-subtree}).
        !          6112: @item C-c C-s
        !          6113: Make everything under this heading visible, including body, subheadings,
        !          6114: and their bodies (@code{show-subtree}).
        !          6115: @item C-c C-i
        !          6116: Make immediate subheadings (one level down) of this heading line visible
        !          6117: (@code{show-children}).
        !          6118: @item M-x hide-entry
        !          6119: Make this heading line's body invisible.
        !          6120: @item M-x show-entry
        !          6121: Make this heading line's body visible.
        !          6122: @item M-x hide-leaves
        !          6123: Make the body of this heading line, and of all its subheadings, invisible.
        !          6124: @item M-x show-branches
        !          6125: Make all subheadings of this heading line, at all levels, visible.
        !          6126: @end table
        !          6127: 
        !          6128: @findex next-visible-heading
        !          6129: @findex previous-visible-heading
        !          6130: @kindex M-@{ (Outline mode)
        !          6131: @kindex M-@} (Outline mode)
        !          6132:   There are two special motion commands in Outline mode.  @kbd{M-@}}
        !          6133: (@code{next-visible-heading}) moves down to the next heading line.
        !          6134: @kbd{M-@{} (@code{previous-visible-heading}) moves similarly backward.
        !          6135: Both accept numeric arguments as repeat counts.  The names emphasize that
        !          6136: invisible headings are skipped, but this is not really a special feature.
        !          6137: All editing commands that look for lines ignore the invisible lines
        !          6138: automatically.@refill
        !          6139: 
        !          6140:   The other special commands of outline mode are used to make lines visible
        !          6141: or invisible.  Their names all start with @code{hide} or @code{show}.
        !          6142: Most of them fall into pairs of opposites.  They are not undoable; instead,
        !          6143: you can undo right past them.  Making lines visible or invisible is simply
        !          6144: not recorded by the undo mechanism.
        !          6145: 
        !          6146: @findex hide-entry
        !          6147: @findex show-entry
        !          6148:   Two commands that are exact opposites are @kbd{M-x hide-entry} and
        !          6149: @kbd{M-x show-entry}.  They are used with point on a heading line, and
        !          6150: apply only to the body lines of that heading.  The subtopics and their
        !          6151: bodies are not affected.
        !          6152: 
        !          6153: @findex hide-subtree
        !          6154: @findex show-subtree
        !          6155: @kindex C-c C-s (Outline mode)
        !          6156: @kindex C-c C-h (Outline mode)
        !          6157: @cindex subtree (Outline mode)
        !          6158:   Two more powerful opposites are @kbd{C-c C-h} (@code{hide-subtree}) and
        !          6159: @kbd{C-c C-s} (@code{show-subtree}).  Both expect to be used when point is
        !          6160: on a heading line, and both apply to all the lines of that heading's
        !          6161: @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
        !          6162: all of their bodies.  In other words, the subtree contains everything
        !          6163: following this heading line, up to and not including the next heading of
        !          6164: the same or higher rank.@refill
        !          6165: 
        !          6166: @findex hide-leaves
        !          6167: @findex show-branches
        !          6168:   Intermediate between a visible subtree and an invisible one is having
        !          6169: all the subheadings visible but none of the body.  There are two commands
        !          6170: for doing this, depending on whether you want to hide the bodies or
        !          6171: make the subheadings visible.  They are @kbd{M-x hide-leaves} and
        !          6172: @kbd{M-x show-branches}.
        !          6173: 
        !          6174: @kindex C-c C-i
        !          6175: @findex show-children
        !          6176:   A little weaker than @code{show-branches} is @kbd{C-c C-i}
        !          6177: (@code{show-children}).  It makes just the direct subheadings
        !          6178: visible---those one level down.  Deeper subheadings remain invisible, if
        !          6179: they were invisible.@refill
        !          6180: 
        !          6181: @findex hide-body
        !          6182: @findex show-all
        !          6183:   Two commands have a blanket effect on the whole file.  @kbd{M-x hide-body}
        !          6184: makes all body lines invisible, so that you see just the outline structure.
        !          6185: @kbd{M-x show-all} makes all lines visible.  These commands can be thought
        !          6186: of as a pair of opposites even though @kbd{M-x show-all} applies to more
        !          6187: than just body lines.
        !          6188: 
        !          6189:   Outline mode makes a line invisible by changing the newline before it
        !          6190: into an ASCII Control-M (code 015).  Most editing commands that work on
        !          6191: lines treat an invisible line as part of the previous line because,
        !          6192: strictly speaking, it @i{is} part of that line, since there is no longer a
        !          6193: newline in between.  When you save the file in Outline mode, Control-M
        !          6194: characters are saved as newlines, so the invisible lines become ordinary
        !          6195: lines in the file.  But saving does not change the visibility status of a
        !          6196: line inside Emacs.
        !          6197: 
        !          6198: @vindex outline-mode-hook
        !          6199:   Entering Outline mode calls with no arguments the value of the variable
        !          6200: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
        !          6201: does the same with the variable @code{outline-mode-hook}.
        !          6202: 
        !          6203: @node Words, Sentences, Text Mode, Text
        !          6204: @section Words
        !          6205: @cindex words
        !          6206: @cindex Meta
        !          6207: 
        !          6208:   Emacs has commands for moving over or operating on words.  By convention,
        !          6209: the keys for them are all @kbd{Meta-} characters.
        !          6210: 
        !          6211: @c widecommands
        !          6212: @table @kbd
        !          6213: @item M-f
        !          6214: Move forward over a word (@code{forward-word}).
        !          6215: @item M-b
        !          6216: Move backward over a word (@code{backward-word}).
        !          6217: @item M-d
        !          6218: Kill up to the end of a word (@code{kill-word}).
        !          6219: @item M-@key{DEL}
        !          6220: Kill back to the beginning of a word (@code{backward-kill-word}).
        !          6221: @item M-@@
        !          6222: Mark the end of the next word (@code{mark-word}).
        !          6223: @item M-t
        !          6224: Transpose two words;  drag a word forward
        !          6225: or backward across other words (@code{transpose-words}).
        !          6226: @end table
        !          6227: 
        !          6228:   Notice how these keys form a series that parallels the
        !          6229: character-based @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @kbd{C-t} and
        !          6230: @key{DEL}.  @kbd{M-@@} is related to @kbd{C-@@}, which is an alias for
        !          6231: @kbd{C-@key{SPC}}.@refill
        !          6232: 
        !          6233: @kindex M-f
        !          6234: @kindex M-b
        !          6235: @findex forward-word
        !          6236: @findex backward-word
        !          6237:   The commands @kbd{Meta-f} (@code{forward-word}) and @kbd{Meta-b}
        !          6238: (@code{backward-word}) move forward and backward over words.  They are thus
        !          6239: analogous to @kbd{Control-f} and @kbd{Control-b}, which move over single
        !          6240: characters.  Like their @kbd{Control-} analogues, @kbd{Meta-f} and
        !          6241: @kbd{Meta-b} move several words if given an argument.  @kbd{Meta-f} with a
        !          6242: negative argument moves backward, and @kbd{Meta-b} with a negative argument
        !          6243: moves forward.  Forward motion stops right after the last letter of the
        !          6244: word, while backward motion stops right before the first letter.@refill
        !          6245: 
        !          6246: @kindex M-d
        !          6247: @findex kill-word
        !          6248:   @kbd{Meta-d} (@code{kill-word}) kills the word after point.  To be
        !          6249: precise, it kills everything from point to the place @kbd{Meta-f} would
        !          6250: move to.  Thus, if point is in the middle of a word, @kbd{Meta-d} kills
        !          6251: just the part after point.  If some punctuation comes between point and the
        !          6252: next word, it is killed along with the word.  If you wish to kill only the
        !          6253: next word but not the punctuation before it, simply do @kbd{Meta-f} to get
        !          6254: the end, and kill the word backwards with @kbd{Meta-@key{DEL}}.
        !          6255: @kbd{Meta-d} takes arguments just like @kbd{Meta-f}.
        !          6256: 
        !          6257: @findex backward-kill-word
        !          6258: @kindex M-DEL
        !          6259:   @kbd{Meta-@key{DEL}} (@code{backward-kill-word}) kills the word before
        !          6260: point.  It kills everything from point back to where @kbd{Meta-b} would
        !          6261: move to.  If point is after the space in @w{@samp{FOO, BAR}}, then
        !          6262: @w{@samp{FOO, }} is killed.  If you wish to kill just @samp{FOO}, do
        !          6263: @kbd{Meta-b Meta-d} instead of @kbd{Meta-@key{DEL}}.
        !          6264: 
        !          6265: @cindex transposition
        !          6266: @kindex M-t
        !          6267: @findex transpose-words
        !          6268:   @kbd{Meta-t} (@code{transpose-words}) exchanges the words before or
        !          6269: containing point with the following word.  The delimiter characters between
        !          6270: the words do not move.  For example, @w{@samp{FOO, BAR}} transposes into
        !          6271: @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.  @xref{Transpose}, for
        !          6272: more on transposition and on arguments to transposition commands.
        !          6273: 
        !          6274: @kindex M-@@
        !          6275: @findex mark-word
        !          6276:   To operate on the next @var{n} words with an operation which applies
        !          6277: between point and mark, you can either set the mark at point and then move
        !          6278: over the words, or you can use the command @kbd{Meta-@@} (@code{mark-word})
        !          6279: which does not move point, but sets the mark where @kbd{Meta-f} would move
        !          6280: to.  It can be given arguments just like @kbd{Meta-f}.
        !          6281: 
        !          6282: @cindex syntax table
        !          6283:   The word commands' understanding of syntax is completely controlled by
        !          6284: the syntax table.  Any character can, for example, be declared to be a word
        !          6285: delimiter.  @xref{Syntax}.
        !          6286: 
        !          6287: @node Sentences, Paragraphs, Words, Text
        !          6288: @section Sentences
        !          6289: @cindex sentences
        !          6290: 
        !          6291:   The Emacs commands for manipulating sentences and paragraphs are mostly
        !          6292: on @kbd{Meta-} keys, so as to be like the word-handling commands.
        !          6293: 
        !          6294: @table @kbd
        !          6295: @item M-a
        !          6296: Move back to the beginning of the sentence (@code{backward-sentence}).
        !          6297: @item M-e
        !          6298: Move forward to the end of the sentence (@code{forward-sentence}).
        !          6299: @item M-k
        !          6300: Kill forward to the end of the sentence (@code{kill-sentence}).
        !          6301: @item C-x @key{DEL}
        !          6302: Kill back to the beginning of the sentence @*(@code{backward-kill-sentence}).
        !          6303: @end table
        !          6304: 
        !          6305: @kindex M-a
        !          6306: @kindex M-e
        !          6307: @findex backward-sentence
        !          6308: @findex forward-sentence
        !          6309:   The commands @kbd{Meta-a} and @kbd{Meta-e} (@code{backward-sentence} and
        !          6310: @code{forward-sentence}) move to the beginning and end of the current
        !          6311: sentence, respectively.  They were chosen to resemble @kbd{Control-a} and
        !          6312: @kbd{Control-e}, which move to the beginning and end of a line.  Unlike
        !          6313: them, @kbd{Meta-a} and @kbd{Meta-e} if repeated or given numeric arguments
        !          6314: move over successive sentences.  Emacs considers a sentence to end wherever
        !          6315: there is a @samp{.}, @samp{?} or @samp{!} followed by the end of a line or
        !          6316: two spaces, with any number of @samp{)}, @samp{]}, @samp{'}, or @samp{"}
        !          6317: characters allowed in between.  A sentence also begins or ends wherever a
        !          6318: paragraph begins or ends.@refill
        !          6319: 
        !          6320:   Neither @kbd{M-a} nor @kbd{M-e} moves past the newline or spaces beyond
        !          6321: the sentence edge at which it is stopping.
        !          6322: 
        !          6323: @kindex M-k
        !          6324: @kindex C-x DEL
        !          6325: @findex kill-sentence
        !          6326: @findex backward-kill-sentence
        !          6327:   Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
        !          6328: with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
        !          6329: @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of the
        !          6330: sentence.  With minus one as an argument it kills back to the beginning of
        !          6331: the sentence.  Larger arguments serve as a repeat count.@refill
        !          6332: 
        !          6333:   There is a special command, @kbd{C-x @key{DEL}}
        !          6334: (@code{backward-kill-sentence}) for killing back to the beginning of a
        !          6335: sentence, because this is useful when you change your mind in the middle of
        !          6336: composing text.@refill
        !          6337: 
        !          6338: @vindex sentence-end
        !          6339:   The variable @code{sentence-end} controls recognition of the end of a
        !          6340: sentence.  It is a regexp that matches the last few characters of a
        !          6341: sentence, together with the whitespace following the sentence.  Its
        !          6342: normal value is
        !          6343: 
        !          6344: @example
        !          6345: "[.?!][]\")]*\\($\\|\t\\|  \\)[ \t\n]*"
        !          6346: @end example
        !          6347: 
        !          6348: @noindent
        !          6349: (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in the
        !          6350: string.)
        !          6351: 
        !          6352: @node Paragraphs, Pages, Sentences, Text
        !          6353: @section Paragraphs
        !          6354: @cindex paragraphs
        !          6355: @kindex M-[
        !          6356: @kindex M-]
        !          6357: @findex backward-paragraph
        !          6358: @findex forward-paragraph
        !          6359: 
        !          6360:   The Emacs commands for manipulating paragraphs are also @kbd{Meta-}
        !          6361: keys.
        !          6362: 
        !          6363: @table @kbd
        !          6364: @item M-[
        !          6365: Move back to previous paragraph beginning @*(@code{backward-paragraph}).
        !          6366: @item M-]
        !          6367: Move forward to next paragraph end (@code{forward-paragraph}).
        !          6368: @item M-h
        !          6369: Put point and mark around this or next paragraph (@code{mark-paragraph}).
        !          6370: @end table
        !          6371: 
        !          6372:   @kbd{Meta-[} moves to the beginning of the current or previous paragraph,
        !          6373: while @kbd{Meta-]} moves to the end of the current or next paragraph.
        !          6374: Blank lines and text formatter command lines separate paragraphs and are
        !          6375: not part of any paragraph.  Also, an indented line starts a new
        !          6376: paragraph.
        !          6377: 
        !          6378:   In major modes for programs (as opposed to Text mode), paragraphs begin
        !          6379: and end only at blank lines.  This makes the paragraph commands continue to
        !          6380: be useful even though there are no paragraphs per se.
        !          6381: 
        !          6382:   When there is a fill prefix, then paragraphs are delimited by all lines
        !          6383: which don't start with the fill prefix.  @xref{Filling}.
        !          6384: 
        !          6385: @kindex M-h
        !          6386: @findex mark-paragraph
        !          6387:   When you wish to operate on a paragraph, you can use the command
        !          6388: @kbd{Meta-h} (@code{mark-paragraph}) to set the region around it.  This
        !          6389: command puts point at the beginning and mark at the end of the paragraph
        !          6390: point was in.  If point is between paragraphs (in a run of blank lines, or
        !          6391: at a boundary), the paragraph following point is surrounded by point and
        !          6392: mark.  If there are blank lines preceding the first line of the paragraph,
        !          6393: one of these blank lines is included in the region.  Thus, for example,
        !          6394: @kbd{M-h C-w} kills the paragraph around or after point.
        !          6395: 
        !          6396: @vindex paragraph-start
        !          6397: @vindex paragraph-separate
        !          6398:   The precise definition of a paragraph boundary is controlled by the
        !          6399: variables @code{paragraph-separate} and @code{paragraph-start}.  The value
        !          6400: of @code{paragraph-start} is a regexp that should match any line that
        !          6401: either starts or separates paragraphs.  The value of
        !          6402: @code{paragraph-separate} is another regexp that should match only lines
        !          6403: that separate paragraphs without being part of any paragraph.  For example,
        !          6404: normally @code{paragraph-start} is @code{"^[ @t{\}t@t{\}n@t{\}f]"} and
        !          6405: @code{paragraph-separate} is @code{"^[ @t{\}t@t{\}f]*$"}.@refill
        !          6406: 
        !          6407:   Normally it is desirable for page boundaries to separate paragraphs.
        !          6408: The default values of these variables recognize the usual separator for
        !          6409: pages.
        !          6410: 
        !          6411: @node Pages, Filling, Paragraphs, Text
        !          6412: @section Pages
        !          6413: 
        !          6414: @cindex pages
        !          6415: @cindex formfeed
        !          6416:   Files are often thought of as divided into @dfn{pages} by the
        !          6417: @dfn{formfeed} character (ASCII Control-L, octal code 014).  For example,
        !          6418: if a file is printed on a line printer, each page of the file, in this
        !          6419: sense, will start on a new page of paper.  Emacs treats a page-separator
        !          6420: character just like any other character.  It can be inserted with @kbd{C-q
        !          6421: C-l}, or deleted with @key{DEL}.  Thus, you are free to paginate your file,
        !          6422: or not.  However, since pages are often meaningful divisions of the file,
        !          6423: commands are provided to move over them and operate on them.
        !          6424: 
        !          6425: @c WideCommands
        !          6426: @table @kbd
        !          6427: @item C-x C-p
        !          6428: Put point and mark around this page (or another page) (@code{mark-page}).
        !          6429: @item C-x [
        !          6430: Move point to previous page boundary (@code{backward-page}).
        !          6431: @item C-x ]
        !          6432: Move point to next page boundary (@code{forward-page}).
        !          6433: @item C-x l
        !          6434: Count the lines in this page (@code{count-lines-page}).
        !          6435: @end table
        !          6436: 
        !          6437: @kindex C-x [
        !          6438: @kindex C-x ]
        !          6439: @findex forward-page
        !          6440: @findex backward-page
        !          6441:   The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
        !          6442: after the previous page delimiter.  If point is already right after a page
        !          6443: delimiter, it skips that one and stops at the previous one.  A numeric
        !          6444: argument serves as a repeat count.  The @kbd{C-x ]} (@code{forward-page})
        !          6445: command moves forward past the next page delimiter.
        !          6446: 
        !          6447: @kindex C-x C-p
        !          6448: @findex mark-page
        !          6449:   The @kbd{C-x C-p} command (@code{mark-page}) puts point at the beginning
        !          6450: of the current page and the mark at the end.  The page delimiter at the end
        !          6451: is included (the mark follows it).  The page delimiter at the front is
        !          6452: excluded (point follows it).  This command can be followed by @kbd{C-w} to
        !          6453: kill a page which is to be moved elsewhere.  If it is inserted after a page
        !          6454: delimiter, at a place where @kbd{C-x ]} or @kbd{C-x [} would take you, then
        !          6455: the page will be properly delimited before and after once again.
        !          6456: 
        !          6457:   A numeric argument to @kbd{C-x C-p} is used to specify which page to go
        !          6458: to, relative to the current one.  Zero means the current page.  One means
        !          6459: the next page, and -1 means the previous one.
        !          6460: 
        !          6461: @kindex C-x l
        !          6462: @findex count-lines-page
        !          6463:   The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
        !          6464: where to break a page in two.  It prints in the echo area the total number
        !          6465: of lines in the current page, and then divides it up into those preceding
        !          6466: the current line and those following, as in
        !          6467: 
        !          6468: @example
        !          6469: Page has 96 (72+25) lines
        !          6470: @end example
        !          6471: 
        !          6472: @noindent
        !          6473:   Notice that the sum is off by one; this is correct if point is not at the
        !          6474: front of a line.
        !          6475: 
        !          6476: @vindex page-delimiter
        !          6477:   The variable @code{page-delimiter} should have as its value a regexp that
        !          6478: matches the beginning of a line that separates pages.  This is what defines
        !          6479: where pages begin.  The normal value of this variable is @code{"^@t{\}f"},
        !          6480: which matches a formfeed character at the beginning of a line.
        !          6481: 
        !          6482: @node Filling, Case, Pages, Text
        !          6483: @section Filling Text
        !          6484: @cindex filling
        !          6485: 
        !          6486: @cindex Auto Fill mode
        !          6487:   With Auto Fill mode, text can be @dfn{filled} (broken up into lines that
        !          6488: fit in a specified width) as you insert it.  If you alter existing text it
        !          6489: may no longer be properly filled; then explicit commands for filling can be
        !          6490: used.
        !          6491: 
        !          6492: @table @kbd
        !          6493: @item M-x auto-fill-mode
        !          6494: Enable or disable Auto Fill mode.
        !          6495: @item @key{SPC}
        !          6496: @itemx @key{RET}
        !          6497: In Auto Fill mode, break lines when appropriate.
        !          6498: @item M-q
        !          6499: Fill current paragraph (@code{fill-paragraph}).
        !          6500: @item M-g
        !          6501: Fill each paragraph in the region (@code{fill-region}).
        !          6502: @item M-x fill-region-as-paragraph.
        !          6503: Fill the region, considering it as one paragraph.
        !          6504: @item M-x fill-individual-paragraphs
        !          6505: Fill the region, considering each change of indentation as starting a
        !          6506: new paragraph.
        !          6507: @item M-s
        !          6508: Center a line.
        !          6509: @end table
        !          6510: 
        !          6511: @findex auto-fill-mode
        !          6512:   @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off if
        !          6513: it was on.  With a positive numeric argument it always turns Auto Fill mode
        !          6514: on, and with a negative argument always turns it off.  You can see when
        !          6515: Auto Fill mode is in effect by the presence of the word @samp{Fill} in the
        !          6516: mode line, inside the parentheses.  Auto Fill mode is a minor mode, turned
        !          6517: on or off for each buffer individually.  @xref{Minor Modes}.
        !          6518: 
        !          6519:   In Auto Fill mode, lines are broken automatically at spaces when they get
        !          6520: longer than the desired width.  Line breaking and rearrangement takes place
        !          6521: only when you type @key{SPC} or @key{RET}.  If you wish to insert a space
        !          6522: or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} or
        !          6523: @kbd{C-q @key{LFD}} (recall that a newline is really a linefeed).  Also,
        !          6524: @kbd{C-o} inserts a newline without line breaking.
        !          6525: 
        !          6526:   Auto Fill mode works well with Lisp mode, because when it makes a new
        !          6527: line in Lisp mode it indents that line with @key{TAB}.  If a line ending in
        !          6528: a comment gets too long, the text of the comment is split into two
        !          6529: comments.
        !          6530: 
        !          6531: @kindex M-q
        !          6532: @findex fill-paragraph
        !          6533:   Auto Fill mode does not refill entire paragraphs.  It can break lines but
        !          6534: cannot merge lines.  So editing in the middle of a paragraph can result in
        !          6535: a paragraph that is not correctly filled.  To refill a paragraph, use the
        !          6536: command @kbd{Meta-q} (@code{fill-paragraph}).  It causes the paragraph that
        !          6537: point is inside, or the one after point if point is between paragraphs, to
        !          6538: be refilled.  All the line-breaks are removed, and then new ones are
        !          6539: inserted where necessary.  @kbd{M-q} can be undone with @kbd{C-_}.
        !          6540: @xref{Undo}.
        !          6541: 
        !          6542: @kindex M-g
        !          6543: @findex fill-region
        !          6544:   To refill many paragraphs, use @kbd{M-g} (@code{fill-region}), which
        !          6545: divides the region into paragraphs and fills each of them.
        !          6546: 
        !          6547: @findex fill-region-as-paragraph
        !          6548:   @kbd{Meta-q} and @kbd{Meta-g} use the same criteria as @kbd{Meta-h} for
        !          6549: finding paragraph boundaries (@pxref{Paragraphs}).  For more control, you
        !          6550: can use @kbd{M-x fill-region-as-paragraph}, which refills everything
        !          6551: between point and mark.  This command recognizes only blank lines as
        !          6552: paragraph separators.@refill
        !          6553: 
        !          6554: @cindex justification
        !          6555:   A numeric argument to @kbd{M-g} or @kbd{M-q} causes it to @dfn{justify}
        !          6556: the text as well as filling it.  This means that extra spaces are inserted
        !          6557: to make the right margin line up exactly at the fill column.  To remove the
        !          6558: extra spaces, use @kbd{M-q} or @kbd{M-g} with no argument.@refill
        !          6559: 
        !          6560: @kindex M-s
        !          6561: @cindex centering
        !          6562: @findex center-line
        !          6563:   The command @kbd{Meta-s} (@code{center-line}) centers the current line
        !          6564: within the current fill column.  With an argument, it centers several lines
        !          6565: individually and moves past them.
        !          6566: 
        !          6567: @vindex fill-column
        !          6568: @vindex default-fill-column
        !          6569:   The maximum line width for filling is in the variable @code{fill-column}.
        !          6570: This variable has a separate value in each buffer; setting it in one buffer
        !          6571: has no effect on any other buffer.  The initial value in a new buffer is
        !          6572: taken from the variable @code{default-fill-column}.
        !          6573: 
        !          6574: @kindex C-x f
        !          6575: @findex set-fill-column
        !          6576:   The easiest way to set @code{fill-column} is to use the command @kbd{C-x
        !          6577: f} (@code{set-fill-column}).  With no argument, it sets @code{fill-column}
        !          6578: to the current horizontal position of point.  With a numeric argument, it
        !          6579: uses that as the new fill column.
        !          6580: 
        !          6581: @cindex fill prefix
        !          6582: @kindex C-x .
        !          6583: @findex set-fill-prefix
        !          6584: @vindex fill-prefix
        !          6585:   To fill a paragraph in which each line starts with a special marker
        !          6586: (which might be a few spaces, giving an indented paragraph), use the
        !          6587: @dfn{fill prefix} feature.  The fill prefix is a string which Emacs expects
        !          6588: every line to start with, and which is not included in filling.  It is
        !          6589: stored in the variable @code{fill-prefix}.
        !          6590: 
        !          6591:   To specify a fill prefix, move to a line that starts with the desired
        !          6592: prefix, put point at the end of the prefix, and give the command
        !          6593: @w{@kbd{C-x .}}@: (@code{set-fill-prefix}).  That's a period after the
        !          6594: @kbd{C-x}.  To turn off the fill prefix, specify an empty prefix: type
        !          6595: @w{@kbd{C-x .}}@: with point at the beginning of a line.@refill
        !          6596: 
        !          6597:   When a fill prefix is in effect, the fill commands remove the fill prefix
        !          6598: from each line before filling and insert it on each line after filling.  In
        !          6599: Auto Fill mode, @key{SPC} also inserts the fill prefix on any new line.
        !          6600: Lines that do not start with the fill prefix are considered to start
        !          6601: paragraphs, both in @kbd{M-q} and the paragraph commands; this is just
        !          6602: right if you are using paragraphs with hanging indentation (every line
        !          6603: indented except the first one).  Lines which are blank or indented once the
        !          6604: prefix is removed also separate or start paragraphs; this is what you want
        !          6605: if you are writing multi-paragraph comments with a comment delimiter on
        !          6606: each line.
        !          6607: 
        !          6608: @findex fill-individual-paragraphs
        !          6609:   Another way to use fill prefixes is through @kbd{M-x
        !          6610: fill-individual-paragraphs}.  This function divides the region into groups
        !          6611: of consecutive lines with the same amount and kind of indentation and fills
        !          6612: each group as a paragraph using its indentation as a fill prefix.
        !          6613: 
        !          6614:   Many users like Auto Fill mode and want to use it in all text files.
        !          6615: Execute the following Lisp expression, perhaps in your init file, to cause
        !          6616: Auto Fill mode to be turned on whenever Text mode is entered:
        !          6617: 
        !          6618: @lisp
        !          6619: (setq text-mode-hook 'turn-on-auto-fill)
        !          6620: @end lisp
        !          6621: 
        !          6622: @node Case,, Filling, Text
        !          6623: @section Case Conversion Commands
        !          6624: @cindex case conversion
        !          6625: 
        !          6626:   Emacs has commands for converting either a single word or any arbitrary
        !          6627: range of text to upper case or to lower case.
        !          6628: 
        !          6629: @c WideCommands
        !          6630: @table @kbd
        !          6631: @item M-l
        !          6632: Convert following word to lower case (@code{downcase-word}).
        !          6633: @item M-u
        !          6634: Convert following word to upper case (@code{upcase-word}).
        !          6635: @item M-c
        !          6636: Capitalize the following word (@code{capitalize-word}).
        !          6637: @item C-x C-l
        !          6638: Convert region to lower case (@code{downcase-region}).
        !          6639: @item C-x C-u
        !          6640: Convert region to upper case (@code{upcase-region}).
        !          6641: @end table
        !          6642: 
        !          6643: @kindex M-l
        !          6644: @kindex M-u
        !          6645: @kindex M-c
        !          6646: @cindex words
        !          6647: @findex downcase-word
        !          6648: @findex upcase-word
        !          6649: @findex capitalize-word
        !          6650:   The word conversion commands are the most useful.  @kbd{Meta-l}
        !          6651: (@code{downcase-word}) converts the word after point to lower case, moving
        !          6652: past it.  Thus, repeating @kbd{Meta-l} converts successive words.
        !          6653: @kbd{Meta-u} (@code{upcase-word}) converts to all capitals instead, while
        !          6654: @kbd{Meta-c} (@code{capitalize-word}) puts the first letter of the word
        !          6655: into upper case and the rest into lower case.  All these commands convert
        !          6656: several words at once if given an argument.  They are especially convenient
        !          6657: for converting a large amount of text from all upper case to mixed case,
        !          6658: because you can move through the text using @kbd{M-l}, @kbd{M-u} or
        !          6659: @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead
        !          6660: to skip a word.
        !          6661: 
        !          6662:   When given a negative argument, the word case conversion commands apply
        !          6663: to the appropriate number of words before point, but do not move point.
        !          6664: This is convenient when you have just typed a word in the wrong case: you
        !          6665: can give the case conversion command and continue typing.
        !          6666: 
        !          6667:   If a word case conversion command is given in the middle of a word, it
        !          6668: applies only to the part of the word which follows point.  This is just
        !          6669: like what @kbd{Meta-d} (@code{kill-word}) does.  With a negative argument,
        !          6670: case conversion applies only to the part of the word before point.
        !          6671: 
        !          6672: @kindex C-x C-l
        !          6673: @kindex C-x C-u
        !          6674: @cindex region
        !          6675: @findex downcase-region
        !          6676: @findex upcase-region
        !          6677:   The other basic case conversion commands are @kbd{C-x C-u}
        !          6678: (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
        !          6679: convert everything between point and mark to the specified case.  Point and
        !          6680: mark do not move.@refill
        !          6681: 
        !          6682: @node Programs, Running, Text, Top
        !          6683: @chapter Editing Programs
        !          6684: @cindex Lisp
        !          6685: @cindex C
        !          6686: 
        !          6687:   Emacs has many commands designed to understand the syntax of programming
        !          6688: languages such as Lisp and C.  These commands can
        !          6689: 
        !          6690: @itemize @bullet
        !          6691: @item
        !          6692: Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
        !          6693: @item
        !          6694: Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
        !          6695: functions, in C).
        !          6696: @item
        !          6697: Show how parentheses balance (@pxref{Matching}).
        !          6698: @item
        !          6699: Insert, kill or align comments (@pxref{Comments}).
        !          6700: @item
        !          6701: Follow the usual indentation conventions of the language
        !          6702: (@pxref{Grinding}).
        !          6703: @end itemize
        !          6704: 
        !          6705:   The commands for words, sentences and paragraphs are very useful in
        !          6706: editing code even though their canonical application is for editing human
        !          6707: language text.  Most symbols contain words (@pxref{Words}); sentences can
        !          6708: be found in strings and comments (@pxref{Sentences}).  Paragraphs per se
        !          6709: are not present in code, but the paragraph commands are useful anyway,
        !          6710: because Lisp mode and C mode define paragraphs to begin and end at blank
        !          6711: lines (@pxref{Paragraphs}).  Judicious use of blank lines to make the
        !          6712: program clearer will also provide interesting chunks of text for the
        !          6713: paragraph commands to work on.
        !          6714: 
        !          6715:   The selective display feature is useful for looking at the overall
        !          6716: structure of a function (@pxref{Selective Display}).  This feature causes
        !          6717: only the lines that are indented less than a specified amount to appear
        !          6718: on the screen.
        !          6719: 
        !          6720: @menu
        !          6721: * Program Modes::       Major modes for editing programs.
        !          6722: * Lists::               Expressions with balanced parentheses.
        !          6723:                          There are editing commands to operate on them.
        !          6724: * Defuns::              Each program is made up of separate functions.
        !          6725:                          There are editing commands to operate on them.
        !          6726: * Grinding::            Adjusting indentation to show the nesting.
        !          6727: * Matching::            Insertion of a close-delimiter flashes matching open.
        !          6728: * Comments::            Inserting, illing and aligning comments.
        !          6729: * Balanced Editing::    Inserting two matching parentheses at once, etc.
        !          6730: * Documentation::       Getting documentation of functions you plan to call.
        !          6731: * Change Log::          Maintaining a change history for your program.
        !          6732: * Tags::                Go direct to any function in your program in one
        !          6733:                          command.  Tags remembers which file it is in.
        !          6734: @end menu
        !          6735: 
        !          6736: @node Program Modes, Lists, Programs, Programs
        !          6737: @section Major Modes for Programming Languages
        !          6738: 
        !          6739: @cindex Lisp mode
        !          6740: @cindex C mode
        !          6741: @cindex Scheme mode
        !          6742:   Emacs also has major modes for the programming languages Lisp, Scheme (a
        !          6743: variant of Lisp), C and Muddle.  Ideally, a major mode should be
        !          6744: implemented for each programming language that you might want to edit with
        !          6745: Emacs; but often the mode for one language can serve for other
        !          6746: syntactically similar languages.  The language modes that exist are those
        !          6747: that someone decided to take the trouble to write.
        !          6748: 
        !          6749:   There are several forms of Lisp mode, which differ in the way they
        !          6750: interface to Lisp execution.  @xref{Lisp Modes}.
        !          6751: 
        !          6752:   Each of the programming language modes defines the @key{TAB} key to run
        !          6753: an indentation function that knows the indentation conventions of that
        !          6754: language and updates the current line's indentation accordingly.  For
        !          6755: example, in C mode @key{TAB} is bound to @code{c-indent-line}.  @key{LFD}
        !          6756: is normally defined to do @key{RET} followed by @key{TAB}; thus, it too
        !          6757: indents in a mode-specific fashion.
        !          6758: 
        !          6759: @kindex DEL
        !          6760: @findex backward-delete-char-untabify
        !          6761:   In most programming languages, indentation is likely to vary from line to
        !          6762: line.  So the major modes for those languages rebind @key{DEL} to treat a
        !          6763: tab as if it were the equivalent number of spaces (using the command
        !          6764: @code{backward-delete-char-untabify}).  This makes it possible to rub out
        !          6765: indentation one column at a time without worrying whether it is made up of
        !          6766: spaces or tabs.  Use @kbd{C-b C-d} to delete a tab character before point,
        !          6767: in these modes.
        !          6768: 
        !          6769:   Programming language modes define paragraphs to be separated only by
        !          6770: blank lines, so that the paragraph commands remain useful.  Auto Fill mode,
        !          6771: if enabled in a programming language major mode, indents the new lines
        !          6772: which it creates.
        !          6773: 
        !          6774: @cindex mode hook
        !          6775: @vindex c-mode-hook
        !          6776: @vindex lisp-mode-hook
        !          6777: @vindex emacs-lisp-mode-hook
        !          6778: @vindex lisp-interaction-mode-hook
        !          6779: @vindex scheme-mode-hook
        !          6780: @vindex muddle-mode-hook
        !          6781:   Turning on a major mode calls a user-supplied function called the
        !          6782: @dfn{mode hook}, which is the value of a Lisp variable.  For example,
        !          6783: turning on C mode calls the value of the variable @code{c-mode-hook} if
        !          6784: that value exists and is non-@code{nil}.  Mode hook variables for other
        !          6785: programming language modes include @code{lisp-mode-hook},
        !          6786: @code{emacs-lisp-mode-hook}, @code{lisp-interaction-mode-hook},
        !          6787: @code{scheme-mode-hook} and @code{muddle-mode-hook}.  The mode hook
        !          6788: function receives no arguments.@refill
        !          6789: 
        !          6790: @node Lists, Defuns, Program Modes, Programs
        !          6791: @section Lists and Sexps
        !          6792: 
        !          6793: @c doublewidecommands
        !          6794: @table @kbd
        !          6795: @item C-M-f
        !          6796: Move forward over a sexp (@code{forward-sexp}).
        !          6797: @item C-M-b
        !          6798: Move backward over a sexp (@code{backward-sexp}).
        !          6799: @item C-M-k
        !          6800: Kill sexp forward (@code{kill-sexp}).
        !          6801: @item C-M-u
        !          6802: Move up and backward in list structure (@code{backward-up-list}).
        !          6803: @item C-M-d
        !          6804: Move down and forward in list structure (@code{down-list}).
        !          6805: @item C-M-n
        !          6806: Move forward over a list (@code{forward-list}).
        !          6807: @item C-M-p
        !          6808: Move backward over a list (@code{backward-list}).
        !          6809: @item C-M-t
        !          6810: Transpose expressions (@code{transpose-sexps}).
        !          6811: @item C-M-@@
        !          6812: Put mark after following expression (@code{mark-sexp}).
        !          6813: @end table
        !          6814: 
        !          6815: @cindex Control-Meta
        !          6816:   By convention, Emacs keys for dealing with balanced expressions are
        !          6817: usually @kbd{Control-Meta-} characters.  They tend to be analogous in
        !          6818: function to their @kbd{Control-} and @kbd{Meta-} equivalents.  These commands
        !          6819: are usually thought of as pertaining to expressions in programming
        !          6820: languages, but can be useful with any language in which some sort of
        !          6821: parentheses exist (including English).
        !          6822: 
        !          6823: @cindex list
        !          6824: @cindex sexp
        !          6825: @cindex expression
        !          6826:   These commands fall into two classes.  Some deal only with @dfn{lists}
        !          6827: (parenthetical groupings).  They see nothing except parentheses, brackets,
        !          6828: braces, and escape characters that might be used to quote those.  The other
        !          6829: commands deal with expressions or @dfn{sexps} (short for @dfn{s-expression}, the
        !          6830: ancient term for a balanced expression in Lisp).  A parenthetical grouping
        !          6831: is one kind of sexp, but a symbol name is also a sexp, and so is a string.
        !          6832: Numbers and character constants can also be sexps.  The idea is to define
        !          6833: the major mode for a language so that the expressions of that language
        !          6834: count as sexps, as much as possible.
        !          6835: 
        !          6836:   Except in Lisp-like languages, not all expressions can be sexps.  For
        !          6837: example, C mode does not recognize @samp{foo + bar} as a sexp, even though
        !          6838: it @i{is} a C expression; it recognizes @samp{foo} as one sexp and @samp{bar} as
        !          6839: another, with the @samp{+} as punctuation between them.  This is a
        !          6840: fundamental ambiguity: both @samp{foo + bar} and @samp{foo} are legitimate
        !          6841: choices for the sexp to move over if point is at the @samp{f}.  Note that
        !          6842: @samp{(foo + bar)} is a sexp in C mode.
        !          6843: 
        !          6844:   Some languages have obscure forms of syntax for expressions that nobody
        !          6845: has bothered to make Emacs understand properly.
        !          6846: 
        !          6847: @kindex C-M-f
        !          6848: @kindex C-M-b
        !          6849: @findex forward-sexp
        !          6850: @findex backward-sexp
        !          6851:   To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}).  If
        !          6852: the first significant character after point is an opening delimiter
        !          6853: (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
        !          6854: moves past the matching closing delimiter.  If the character begins a
        !          6855: symbol, string, or number, @kbd{C-M-f} moves over that.  If the character
        !          6856: after point is a closing delimiter, @kbd{C-M-f} just moves past it.  (This
        !          6857: last is not really moving across a sexp; it is an exception which is
        !          6858: included in the definition of @kbd{C-M-f} because it is as useful a
        !          6859: behavior as anyone can think of for that situation.)@refill
        !          6860: 
        !          6861:   The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
        !          6862: sexp.  The detailed rules are like those above for @kbd{C-M-f}, but with
        !          6863: directions reversed.  If there are any prefix characters (singlequote,
        !          6864: backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
        !          6865: over them as well.
        !          6866: 
        !          6867:   @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
        !          6868: specified number of times; with a negative argument, it moves in the
        !          6869: opposite direction.
        !          6870: 
        !          6871:   The sexp commands move across comments as if they were whitespace, in
        !          6872: languages such as C where the comment-terminator can be recognized.  In
        !          6873: Lisp, and other languages where comments run until the end of a line, it is
        !          6874: very difficult to ignore comments when parsing backwards; therefore, in
        !          6875: such languages the sexp commands treat the text of comments as if it were
        !          6876: code.
        !          6877: 
        !          6878: @kindex C-M-k
        !          6879: @findex kill-sexp
        !          6880:   Killing a sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
        !          6881: @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.
        !          6882: 
        !          6883: @kindex C-M-n
        !          6884: @kindex C-M-p
        !          6885: @findex forward-list
        !          6886: @findex backward-list
        !          6887:   The @dfn{list commands} move over lists like the sexp commands but skip
        !          6888: blithely over any number of other kinds of sexps (symbols, strings, etc).
        !          6889: They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
        !          6890: (@code{backward-list}).  The main reason they are useful is that they
        !          6891: usually ignore comments (since the comments usually do not contain any
        !          6892: lists).@refill
        !          6893: 
        !          6894: @kindex C-M-u
        !          6895: @kindex C-M-d
        !          6896: @findex backward-up-list
        !          6897: @findex down-list
        !          6898:   @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
        !          6899: that's possible.  To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u}
        !          6900: (@code{backward-up-list}).
        !          6901: @kbd{C-M-u} moves backward up past one unmatched opening delimiter.  A
        !          6902: positive argument serves as a repeat count; a negative argument reverses
        !          6903: direction of motion and also requests repetition, so it moves forward and
        !          6904: up one or more levels.@refill
        !          6905: 
        !          6906:   To move @i{down} in list structure, use @kbd{C-M-d} (@code{down-list}).  In Lisp mode,
        !          6907: where @samp{(} is the only opening delimiter, this is nearly the same as
        !          6908: searching for a @samp{(}.
        !          6909: 
        !          6910: @cindex transposition
        !          6911: @kindex C-M-t
        !          6912: @findex transpose-sexps
        !          6913:   A somewhat random-sounding command which is nevertheless easy to use is
        !          6914: @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp across
        !          6915: the next one.  An argument serves as a repeat count, and a negative
        !          6916: argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with
        !          6917: a positive argument).  An argument of zero, rather than doing nothing,
        !          6918: transposes the sexps ending after point and the mark.
        !          6919: 
        !          6920: @kindex C-M-@@
        !          6921: @findex mark-sexp
        !          6922:   To make the region be the next sexp in the buffer, use @kbd{C-M-@@}
        !          6923: (@code{mark-sexp}) which sets mark at the same place that @kbd{C-M-f} would
        !          6924: move to.  @kbd{C-M-@@} takes arguments like @kbd{C-M-f}.  In particular, a
        !          6925: negative argument is useful for putting the mark at the beginning of the
        !          6926: previous sexp.
        !          6927: 
        !          6928:   The list and sexp commands' understanding of syntax is completely
        !          6929: controlled by the syntax table.  Any character can, for example, be
        !          6930: declared to be an opening delimiter and act like an open parenthesis.
        !          6931: @xref{Syntax}.
        !          6932: 
        !          6933: @node Defuns, Grinding, Lists, Programs
        !          6934: @section Defuns
        !          6935: @cindex defuns
        !          6936: 
        !          6937:   In Emacs, a list at the top level in the buffer is called a @dfn{defun}.
        !          6938: The name derives from the fact that most top level lists in a Lisp file are
        !          6939: instances of the special form @code{defun}, but any top level list counts
        !          6940: as a defun in Emacs parlance regardless of what its contents are, and
        !          6941: regardless of the programming language in use.  For example, in C, the body
        !          6942: of a function definition is a defun.
        !          6943: 
        !          6944: @c doublewidecommands
        !          6945: @table @kbd
        !          6946: @item C-M-a
        !          6947: Move to beginning of current or preceding defun
        !          6948: (@code{beginning-of-defun}).
        !          6949: @item C-M-e
        !          6950: Move to end of current or following defun (@code{end-of-defun}).
        !          6951: @item C-M-h
        !          6952: Put region around whole current or following defun (@code{mark-defun}).
        !          6953: @end table
        !          6954: 
        !          6955: @kindex C-M-a
        !          6956: @kindex C-M-e
        !          6957: @kindex C-M-h
        !          6958: @findex beginning-of-defun
        !          6959: @findex end-of-defun
        !          6960: @findex mark-defun
        !          6961:   The commands to move to the beginning and end of the current defun are
        !          6962: @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
        !          6963: 
        !          6964:   If you wish to operate on the current defun, use @kbd{C-M-h}
        !          6965: (@code{mark-defun}) which puts point at the beginning and mark at the end
        !          6966: of the current or next defun.  For example, this is the easiest way to get
        !          6967: ready to move the defun to a different place in the text.  In C mode,
        !          6968: @kbd{C-M-h} runs the function @code{mark-c-function}, which is almost the
        !          6969: same as @code{mark-defun}; the difference is that it backs up over the
        !          6970: argument declarations, function name and returned data type so that the
        !          6971: entire C function is inside the region.
        !          6972: 
        !          6973:   Emacs assumes that any open-parenthesis found in the leftmost column is
        !          6974: the start of a defun.  Therefore, @b{never put an open-parenthesis at the
        !          6975: left margin in a Lisp file unless it is the start of a top level list.
        !          6976: Never put an open-brace or other opening delimiter at the beginning of a
        !          6977: line of C code unless it starts the body of a function.}  The most likely
        !          6978: problem case is when you want an opening delimiter at the start of a line
        !          6979: inside a string.  To avoid trouble, put an escape character (@samp{\}, in C
        !          6980: and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening
        !          6981: delimiter.  It will not affect the contents of the string.
        !          6982: 
        !          6983:   In the remotest past, the original Emacs found defuns by moving upward a
        !          6984: level of parentheses until there were no more levels to go up.  This always
        !          6985: required scanning all the way back to the beginning of the buffer, even for
        !          6986: a small function.  To speed up the operation, Emacs was changed to assume
        !          6987: that any @samp{(} (or other character assigned the syntactic class of
        !          6988: opening-delimiter) at the left margin is the start of a defun.  This
        !          6989: heuristic was nearly always right and avoided the costly scan; however,
        !          6990: it mandated the convention described above.
        !          6991: 
        !          6992: @node Grinding, Matching, Defuns, Programs
        !          6993: @section Indentation for Programs
        !          6994: @cindex indentation
        !          6995: @cindex grinding
        !          6996: 
        !          6997:   The best way to keep a program properly indented (``ground'') is to use
        !          6998: Emacs to re-indent it as you change it.  Emacs has commands to indent
        !          6999: properly either a single line, a specified number of lines, or all of the
        !          7000: lines inside a single parenthetical grouping.
        !          7001: 
        !          7002: @c WideCommands
        !          7003: @table @kbd
        !          7004: @item @key{TAB}
        !          7005: Adjust indentation of current line.
        !          7006: @item @key{LFD}
        !          7007: Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
        !          7008: @item C-M-q
        !          7009: Re-indent all the lines within one list (@code{indent-sexp}).
        !          7010: @item C-u @key{TAB}
        !          7011: Shift an entire list rigidly sideways so that its first line
        !          7012: is properly indented.
        !          7013: @item C-M-\
        !          7014: Re-indent all lines in the region (@code{indent-region}).
        !          7015: @end table
        !          7016: 
        !          7017: @kindex TAB
        !          7018: @findex c-indent-line
        !          7019: @findex lisp-indent-line
        !          7020:   The basic indentation command is @key{TAB}, which gives the current line
        !          7021: the correct indentation as determined from the previous lines.  The
        !          7022: function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
        !          7023: in Lisp mode, @code{c-indent-line} in C mode, etc.  These functions
        !          7024: understand different syntaxes for different languages, but they all do
        !          7025: about the same thing.  @key{TAB} in any programming language major mode
        !          7026: inserts or deletes whitespace at the beginning of the current line,
        !          7027: independent of where point is in the line.  If point is inside the
        !          7028: whitespace at the beginning of the line, @key{TAB} leaves it at the end of
        !          7029: that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
        !          7030: the characters around it.
        !          7031: 
        !          7032:   Use @kbd{C-q @key{TAB}} to insert a tab at point.
        !          7033: 
        !          7034: @kindex LFD
        !          7035: @findex newline-and-indent
        !          7036:   When entering a large amount of new code, use @key{LFD} (@code{newline-and-indent}),
        !          7037: which is equivalent to a @key{RET} followed by a @key{TAB}.  @key{LFD} creates
        !          7038: a blank line, and then gives it the appropriate indentation.
        !          7039: 
        !          7040:   @key{TAB} indents the second and following lines of the body of an
        !          7041: parenthetical grouping each under the preceding one; therefore, if you
        !          7042: alter one line's indentation to be nonstandard, the lines below will tend
        !          7043: to follow it.  This is the right behavior in cases where the standard
        !          7044: result of @key{TAB} is unaesthetic.
        !          7045: 
        !          7046:   Remember that an open-parenthesis, open-brace or other opening delimiter
        !          7047: at the left margin is assumed by Emacs (including the indentation routines)
        !          7048: to be the start of a function.  Therefore, you must never have an opening
        !          7049: delimiter in column zero that is not the beginning of a function; not even
        !          7050: inside a string.  This restriction is vital for making the indentation
        !          7051: commands fast; you must simply accept it.  @xref{Defuns}, for more
        !          7052: information on this.
        !          7053: 
        !          7054: @subsection Indenting Several Lines
        !          7055: 
        !          7056:   When you wish to re-indent code which has been altered or moved to a
        !          7057: different level in the list structure, you have several commands available.
        !          7058: 
        !          7059: @kindex C-M-q
        !          7060: @findex indent-sexp
        !          7061: @findex indent-c-exp
        !          7062:   You can re-indent the contents of a single list by positioning point
        !          7063: before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
        !          7064: Lisp mode, @code{indent-c-exp} in C mode; also bound to other suitable
        !          7065: functions in other modes).  The indentation of the line the sexp starts on
        !          7066: is not changed; therefore, only the relative indentation within the list,
        !          7067: and not its position, is changed.  To correct the position as well, type a
        !          7068: @key{TAB} before the @kbd{C-M-q}.
        !          7069: 
        !          7070: @kindex C-u TAB
        !          7071:   If the relative indentation within a list is correct but the indentation
        !          7072: of its beginning is not, go to the line the list begins on and type
        !          7073: @kbd{C-u @key{TAB}}.  When @key{TAB} is given a numeric argument, it moves all the
        !          7074: lines in the grouping starting on the current line sideways the same amount
        !          7075: that the current line moves.  It is clever, though, and does not move lines
        !          7076: that start inside strings, or C preprocessor lines when in C mode.
        !          7077: 
        !          7078: @kindex C-M-\
        !          7079: @findex indent-region
        !          7080:   Another way to specify the range to be re-indented is with point and
        !          7081: mark.  The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to every line
        !          7082: whose first character is between point and mark.
        !          7083:  
        !          7084: @subsection Customizing Lisp Indentation
        !          7085: @cindex customization
        !          7086: 
        !          7087:   The indentation pattern for a Lisp expression can depend on the function
        !          7088: called by the expression.  For each Lisp function, you can choose among
        !          7089: several predefined patterns of indentation, or define an arbitrary one with
        !          7090: a Lisp program.
        !          7091: 
        !          7092:   The standard pattern of indentation is as follows: the second line of the
        !          7093: expression is indented under the first argument, if that is on the same
        !          7094: line as the beginning of the expression; otherwise, the second line is
        !          7095: indented underneath the function name.  Each following line is indented
        !          7096: under the previous line whose nesting depth is the same.
        !          7097: 
        !          7098: @vindex lisp-indent-offset
        !          7099:   If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
        !          7100: the usual indentation pattern for the second line of an expression, so that
        !          7101: such lines are always indented @code{lisp-indent-offset} more columns than
        !          7102: the containing list.
        !          7103: 
        !          7104: @vindex lisp-body-indention
        !          7105:   The standard pattern is overridded for certain functions.  Functions
        !          7106: whose names start with @code{def} always indent the second line by
        !          7107: @code{lisp-body-indention} extra columns beyond the open-parenthesis
        !          7108: starting the expression.
        !          7109: 
        !          7110:   The standard pattern can be overridden in various ways for individual
        !          7111: functions, according to the @code{lisp-indent-hook} property of the
        !          7112: function name.  There are four possibilities for this property:
        !          7113: 
        !          7114: @table @asis
        !          7115: @item @code{nil}
        !          7116: This is the same as no property; the standard indentation pattern is used.
        !          7117: @item @code{defun}
        !          7118: The pattern used for function names that start with @code{def} is used for
        !          7119: this function also.
        !          7120: @item a number, @var{number}
        !          7121: The first @var{number} arguments of the function are
        !          7122: @dfn{distinguished} arguments; the rest are considered the @dfn{body}
        !          7123: of the expression.  A line in the expression is indented according to
        !          7124: whether the first argument on it is distinguished or not.  If the
        !          7125: argument is part of the body, the line is indented @code{lisp-body-indent}
        !          7126: more columns than the open-parenthesis starting the containing
        !          7127: expression.  If the argument is distinguished and is either the first
        !          7128: or second argument, it is indented @i{twice} that many extra columns.
        !          7129: If the argument is distinguished and not the first or second argument,
        !          7130: the standard pattern is followed for that line.
        !          7131: @item a symbol, @var{symbol}
        !          7132: @var{symbol} should be a function name; that function is called to
        !          7133: calculate the indentation of a line within this expression.  The
        !          7134: function receives two arguments:
        !          7135: @table @asis
        !          7136: @item @var{state}
        !          7137: The value returned by @code{parse-partial-sexp} (a Lisp primitive for
        !          7138: indentation and nesting computation) when it parses up to the
        !          7139: beginning of this line.
        !          7140: @item @var{pos}
        !          7141: The position at which the line being indented begins.
        !          7142: @end table
        !          7143: @noindent
        !          7144: It should return either a number, which is the number of columns of
        !          7145: indentation for that line, or a list whose car is such a number.  The
        !          7146: difference between returning a number and returning a list is that a
        !          7147: number says that all following lines at the same nesting level should
        !          7148: be indented just like this one; a list says that following lines might
        !          7149: call for different indentations.  This makes a difference when the
        !          7150: indentation is being computed by @kbd{C-M-q}; if the value is a
        !          7151: number, @kbd{C-M-q} need not recalculate indentation for the following
        !          7152: lines until the end of the list.
        !          7153: @end table
        !          7154: 
        !          7155: @subsection Customizing C Indentation
        !          7156: 
        !          7157:   C does not have anything analogous to particular function names for which
        !          7158: special forms of indentation are desirable.  However, it has a different
        !          7159: need for customization facilities: many different styles of C indentation
        !          7160: are in common use.  There are six variables you can set to control the
        !          7161: style that Emacs C mode will use.
        !          7162: 
        !          7163: @vindex c-indent-level
        !          7164:   The variable @code{c-indent-level} controls the indentation for C
        !          7165: statements with respect to the surrounding block.  In the example
        !          7166: 
        !          7167: @example
        !          7168:     @{
        !          7169:       foo ();
        !          7170: @end example
        !          7171: 
        !          7172: @noindent
        !          7173: the difference in indentation between the lines is @code{c-indent-level}.
        !          7174: Its standard value is 2.
        !          7175: 
        !          7176: If the open-brace beginning the compound statement is not at the beginning
        !          7177: of its line, the @code{c-indent-level} is added to the indentation of the
        !          7178: line, not the column of the open-brace.  For example,
        !          7179: 
        !          7180: @example
        !          7181: if (losing) @{
        !          7182:   do_this ();
        !          7183: @end example
        !          7184: 
        !          7185: @noindent
        !          7186: One popular indentation style is that which results from setting
        !          7187: @code{c-indent-level} to 8 and putting open-braces at the end of a line in
        !          7188: this way.
        !          7189: 
        !          7190: @vindex c-brace-imaginary-offset
        !          7191:   In fact, the value of the variable @code{c-brace-imaginary-offset} is
        !          7192: also added to the indentation of such a statement.  Normally this variable
        !          7193: is zero.  Think of this variable as the imaginary position of the open
        !          7194: brace, relative to the first nonblank character on the line.  By setting
        !          7195: this variable to 4 and @code{c-indent-level} to 0, you can get this style:
        !          7196: 
        !          7197: @example
        !          7198: if (x == y) @{
        !          7199:     do_it ();
        !          7200:     @}
        !          7201: @end example
        !          7202: 
        !          7203:   When @code{c-indent-level} is zero, the statements inside most braces
        !          7204: will line up right under the open brace.  But there is an exception made
        !          7205: for braces in column zero, such as surrounding a function's body.  The
        !          7206: statements just inside it do not go at column zero.  Instead,
        !          7207: @code{c-brace-offset} and @code{c-continued-statement-offset} (see below)
        !          7208: are added to produce a typical offset between brace levels, and the
        !          7209: statements are indented that far.
        !          7210: 
        !          7211: @vindex c-continued-statement-offset
        !          7212:   @code{c-continued-statement-offset} controls the extra indentation for a
        !          7213: line that starts within a statement (but not within parentheses or
        !          7214: brackets).  These lines are usually statements that are within other
        !          7215: statements, such as the then-clauses of @code{if} statements and the bodies
        !          7216: of @code{while} statements.  This parameter is the difference in
        !          7217: indentation between the two lines in
        !          7218: 
        !          7219: @example
        !          7220: if (x == y)
        !          7221:   do_it ();
        !          7222: @end example
        !          7223: 
        !          7224: @noindent
        !          7225: Its standard value is 2.  Some popular indentation styles correspond to a
        !          7226: value of zero for @code{c-continued-statement-offset}.
        !          7227: 
        !          7228: @vindex c-brace-offset
        !          7229:   @code{c-brace-offset} is the extra indentation given to a line that
        !          7230: starts with an open-brace.  Its standard value is zero;
        !          7231: compare
        !          7232: 
        !          7233: @example
        !          7234: if (x == y)
        !          7235:   @{
        !          7236: @end example
        !          7237: 
        !          7238: @noindent
        !          7239: with
        !          7240: 
        !          7241: @example
        !          7242: if (x == y)
        !          7243:   do_it ();
        !          7244: @end example
        !          7245: 
        !          7246: @noindent
        !          7247: if @code{c-brace-offset} were set to 4, the first example would become
        !          7248: 
        !          7249: @example
        !          7250: if (x == y)
        !          7251:       @{
        !          7252: @end example
        !          7253: 
        !          7254: @vindex c-argdecl-indent
        !          7255:   @code{c-argdecl-indent} controls the indentation of declarations of the
        !          7256: arguments of a C function.  It is absolute: argument declarations receive
        !          7257: exactly @code{c-argdecl-indent} spaces.  The standard value is 5, resulting
        !          7258: in code like this:
        !          7259: 
        !          7260: @example
        !          7261: char *
        !          7262: index (string, char)
        !          7263:      char *string;
        !          7264:      int char;
        !          7265: @end example
        !          7266: 
        !          7267: @vindex c-label-offset
        !          7268:   @code{c-label-offset} is the extra indentation given to a line that
        !          7269: contains a label, a case statement, or a default statement.  Its standard
        !          7270: value is -2, resulting in code like this
        !          7271: 
        !          7272: @example
        !          7273: switch (c)
        !          7274:   @{
        !          7275:   case 'x':
        !          7276: @end example
        !          7277: 
        !          7278: @noindent
        !          7279: If @code{c-label-offset} were zero, the same code would be indented as
        !          7280: 
        !          7281: @example
        !          7282: switch (c)
        !          7283:   @{
        !          7284:     case 'x':
        !          7285: @end example
        !          7286: 
        !          7287: @noindent
        !          7288: This example assumes that the other variables above also have their
        !          7289: standard values.
        !          7290: 
        !          7291:   I strongly recommend that you try out the indentation style produced by
        !          7292: the standard settings of these variables, together with putting open braces
        !          7293: on separate lines.  You can see how it looks in all the C source files of
        !          7294: GNU Emacs.
        !          7295: 
        !          7296: @vindex c-auto-newline
        !          7297:   One other variable, @code{c-auto-newline}, does not affect the style of
        !          7298: indentation that is used, but makes insertion of certain characters insert
        !          7299: newlines automatically.  When this variable is non-@code{nil}, newlines are
        !          7300: inserted both before and after braces that you insert, and after colons and
        !          7301: semicolons.  Correct C indentation is done on all the lines that are made
        !          7302: this way.
        !          7303: 
        !          7304: @node Matching, Comments, Grinding, Programs
        !          7305: @section Automatic Display Of Matching Parentheses
        !          7306: @cindex matching parentheses
        !          7307: @cindex parentheses
        !          7308: 
        !          7309:   The Emacs parenthesis-matching feature is designed to show automatically
        !          7310: how parentheses match in the text.  When ever a self-inserting character
        !          7311: that is a closing delimiter is typed, the cursor moves momentarily to the
        !          7312: location of the matching opening delimiter, provided that is on the screen.
        !          7313: If it is not on the screen, some text starting with that opening delimiter
        !          7314: is displayed in the echo area.  Either way, you can tell what grouping is
        !          7315: being closed off.
        !          7316: 
        !          7317:   In Lisp, automatic matching applies only to parentheses.  In C, it
        !          7318: applies to braces and brackets too.  Emacs knows which characters to regard
        !          7319: as matching delimiters based on the syntax table, which is set by the major
        !          7320: mode.  @xref{Syntax}.
        !          7321: 
        !          7322:   If the opening delimiter and closing delimiter are mismatched---such as,
        !          7323: in @samp{[x)}---a warning message is displayed in the echo area.  The
        !          7324: correct matches are specified in the syntax table.
        !          7325: 
        !          7326: @vindex blink-matching-paren
        !          7327: @vindex blink-matching-paren-distance
        !          7328:   Two variables control parenthesis match display.  @code{blink-matching-paren}
        !          7329: turns the feature on or off; @code{nil} turns it off, but the default is
        !          7330: @code{t} to turn match display on.  @code{blink-matching-paren-distance}
        !          7331: specifies how many characters back to search to find the matching opening
        !          7332: delimiter.  If the match is not found in that far, scanning stops, and
        !          7333: nothing is displayed.  This is to prevent scanning for the matching
        !          7334: delimiter from wasting lots of time when there is no match.
        !          7335: 
        !          7336: @node Comments, Balanced Editing, Matching, Programs
        !          7337: @section Manipulating Comments
        !          7338: @cindex comments
        !          7339: @kindex M-;
        !          7340: @cindex indentation
        !          7341: @findex indent-for-comment
        !          7342: 
        !          7343:   The comment commands insert, kill and align comments.  There are also
        !          7344: commands for moving through existing code and inserting comments.
        !          7345: 
        !          7346: @c WideCommands
        !          7347: @table @kbd
        !          7348: @item M-;
        !          7349: Insert or align comment (@code{indent-for-comment}).
        !          7350: @item C-x ;
        !          7351: Set comment column (@code{set-comment-column}).
        !          7352: @item C-u - C-x ;
        !          7353: Kill comment on current line (@code{kill-comment}).  With region, kill
        !          7354: comments in region.
        !          7355: @item M-@key{LFD}
        !          7356: Like @key{RET} followed by inserting and aligning the @code{comment-start}
        !          7357: string (@code{indent-new-comment-line}).
        !          7358: @end table
        !          7359: 
        !          7360:   The command that creates a comment is @kbd{Meta-;} (@code{indent-for-comment}).
        !          7361: If there is no comment already on the line, a new comment is created,
        !          7362: aligned at a specific column called the @dfn{comment column}.  The comment
        !          7363: is created by inserting the string Emacs thinks comments should start with
        !          7364: (the value of @code{comment-start}; see below).  Point is left after that
        !          7365: string.  If the text of the line extends past the comment column, then the
        !          7366: indentation is done to a suitable boundary (usually, at least one space is
        !          7367: inserted).  If the major mode has specified a string to terminate comments,
        !          7368: that is inserted after point, to keep the syntax valid.
        !          7369: 
        !          7370:   @kbd{Meta-;} can also be used to align an existing comment.  If a line
        !          7371: already contains the string that starts comments, then @kbd{M-;} just moves
        !          7372: point after it and re-indents it to the right column.  Exception: comments
        !          7373: starting in column 0 are not moved.  Also, in particular modes, there are
        !          7374: special rules for indenting certain kinds of comments in certain contexts.
        !          7375: 
        !          7376:   For example, in Lisp code, comments which start with two semicolons are
        !          7377: indented as if they were lines of code, instead of at the comment column.
        !          7378: Comments which start with three semicolons are supposed to start at the
        !          7379: left margin.  Emacs understands these conventions by indenting a
        !          7380: double-semicolon comment using @key{TAB}, and by not changing the
        !          7381: indentation of a triple-semicolon comment at all.
        !          7382: 
        !          7383:   In C code, a comment preceded on its line by nothing but whitespace
        !          7384: is indented like a line of code.
        !          7385: 
        !          7386:   Even when an existing comment is properly aligned, @kbd{M-;} is still
        !          7387: useful for moving directly to the start of the comment.
        !          7388: 
        !          7389: @kindex C-u - C-x ;
        !          7390: @findex kill-comment
        !          7391:   @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
        !          7392: if there is one.  The indentation before the start of the comment is killed
        !          7393: as well.  If there does not appear to be a comment in the line, nothing is
        !          7394: done.  To reinsert the comment on another line, move to the end of that
        !          7395: line, do @kbd{C-y}, and then do @kbd{M-;} to realign it.  Note that
        !          7396: @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
        !          7397: with a negative argument.  That command is programmed so that when it
        !          7398: receives a negative argument it calls @code{kill-comment}.  However,
        !          7399: @code{kill-comment} is a valid command which you could bind directly to a
        !          7400: key if you wanted to.
        !          7401: 
        !          7402: @subsection Multiple Lines of Comments
        !          7403: 
        !          7404:   If you wish to align a large number of comments, give @kbd{Meta-;} an
        !          7405: argument, and it indents what comments exist on that many lines, creating
        !          7406: none.  Point is left after the last line processed (unlike the no-argument
        !          7407: case).
        !          7408: 
        !          7409: @kindex M-LFD
        !          7410: @cindex blank lines
        !          7411: @cindex Auto Fill mode
        !          7412: @findex indent-new-comment-line
        !          7413:   If you are typing a comment and find that you wish to continue it on
        !          7414: another line, you can use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}),
        !          7415: which terminates the comment you are typing, creates a new blank line
        !          7416: afterward, and begins a new comment indented under the old one.  When Auto
        !          7417: Fill mode is on, going past the fill column while typing a comment causes
        !          7418: the comment to be continued in just this fashion.  If point is not at the
        !          7419: end of the line when @kbd{M-@key{LFD}} is typed, the text on the rest of
        !          7420: the line becomes part of the new comment line.
        !          7421: 
        !          7422: @subsection Options Controlling Comments
        !          7423: 
        !          7424: @vindex comment-column
        !          7425: @kindex C-x ;
        !          7426: @findex set-comment-column
        !          7427:   The comment column is stored in the variable @code{comment-column}.  You
        !          7428: can set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
        !          7429: (@code{set-comment-column}) sets the comment column to the column point is
        !          7430: at.  @kbd{C-u C-x ;} sets the comment column to match the last comment
        !          7431: before point in the buffer, and then does a @kbd{Meta-;} to align the
        !          7432: current line's comment under the previous one.  Note that @kbd{C-u - C-x ;}
        !          7433: runs the function @code{kill-comment} as described above.
        !          7434: 
        !          7435: @cindex major modes
        !          7436:   Many major modes supply default local values for the comment column.
        !          7437: @xref{Locals}.
        !          7438: 
        !          7439: @vindex comment-start-skip
        !          7440:   The comment commands recognize comments based on the regular expression
        !          7441: that is the value of the variable @code{comment-start-skip}.  This regexp
        !          7442: should not match the null string.  It may match more than the comment
        !          7443: starting delimiter in the strictest sense of the word; for example, in C
        !          7444: mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra
        !          7445: stars and spaces after the @samp{/*} itself.  (Note that @samp{\\} is
        !          7446: needed in Lisp syntax to include a @samp{\} in the string, which is needed
        !          7447: to deny the first star its special meaning in regexp syntax; @pxref{Regexps})
        !          7448: 
        !          7449: @vindex comment-start
        !          7450: @vindex comment-end
        !          7451:   When a comment command makes a new comment, it inserts the value of
        !          7452: @code{comment-start} to begin it.  The value of @code{comment-end} is
        !          7453: inserted after point, so that it will follow the text that you will insert
        !          7454: into the comment.  In C mode, @code{comment-start} has the value
        !          7455: @code{"/* "} and @code{comment-end} has the value @code{" */"}.
        !          7456: 
        !          7457: @vindex comment-multi-line
        !          7458:   @code{comment-multi-line} controls how @kbd{M-@key{LFD}} (@code{indent-new-comment-line})
        !          7459: behaves when used inside a comment.  If @code{comment-multi-line} is
        !          7460: @code{nil}, as it normally is, then the comment on the starting line is
        !          7461: terminated and a new comment is started on the new following line.  If
        !          7462: @code{comment-multi-line} is not @code{nil}, then the new following line is
        !          7463: set up as part of the same comment that was found on the starting line.
        !          7464: This is done by not inserting a terminator on the old line, and not
        !          7465: inserting a starter on the new line.  In languages where multi-line comments
        !          7466: work, the choice of value for this variable is a matter of taste.
        !          7467: 
        !          7468: @vindex comment-indent-hook
        !          7469:   The variable @code{comment-indent-hook} should contain a function that
        !          7470: will be called to compute the indentation for a newly inserted comment or
        !          7471: for aligning an existing comment.  It is set differently by various major
        !          7472: modes.  The function is called with no arguments, but with point at the
        !          7473: beginning of the comment, or at the end of a line if a new comment is to be
        !          7474: inserted.  It should return the column in which the comment ought to start.
        !          7475: For example, in Lisp mode, the indent hook function bases its decision
        !          7476: on how many semicolons begin an existing comment, and on the code in the
        !          7477: preceding lines.
        !          7478: 
        !          7479: @node Balanced Editing, Documentation, Comments, Programs
        !          7480: @section Editing Without Unbalanced Parentheses
        !          7481: 
        !          7482: @table @kbd
        !          7483: @item M-(
        !          7484: Put parentheses around next sexp(s) (@code{insert-parentheses}).
        !          7485: @item M-)
        !          7486: Move past next close parenthesis and re-indent
        !          7487: (@code{move-over-close-and-reindent}).
        !          7488: @end table
        !          7489: 
        !          7490: @kindex M-(
        !          7491: @kindex M-)
        !          7492: @findex insert-parentheses
        !          7493: @findex move-over-close-and-reindent
        !          7494:   The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
        !          7495: (@code{move-over-close-and-reindent}) are designed to facilitate a style of
        !          7496: editing which keeps parentheses balanced at all times.  @kbd{M-(} inserts a
        !          7497: pair of parentheses, either together as in @samp{()}, or, if given an
        !          7498: argument, around the next several sexps, and leaves point after the open
        !          7499: parenthesis.  Instead of typing @kbd{( F O O )}, you can type @kbd{M-( F O
        !          7500: O}, which has the same effect except for leaving the cursor before the
        !          7501: close parenthesis.  Then you would type @kbd{M-)}, which moves past the
        !          7502: close parenthesis, deleting any indentation preceding it (in this example
        !          7503: there is none), and indenting with @key{LFD} after it.
        !          7504: 
        !          7505: @node Documentation, Change Log, Balanced Editing, Programs
        !          7506: @section Documentation Commands
        !          7507: 
        !          7508: @kindex C-h f
        !          7509: @findex describe-function
        !          7510: @kindex C-h v
        !          7511: @findex describe-variable
        !          7512:   As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
        !          7513: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
        !          7514: be used to print documentation of functions and variables that you want to
        !          7515: call.  These commands use the minibuffer to read the name of a function or
        !          7516: variable to document, and display the documentation in a window.
        !          7517: 
        !          7518:   For extra convenience, these commands provide default arguments based on
        !          7519: the code in the neighborhood of point.  @kbd{C-h f} sets the default to the
        !          7520: function called in the innermost list containing point.  @kbd{C-h v} uses
        !          7521: the symbol name around or adjacent to point as its default.
        !          7522: 
        !          7523: @findex manual-entry
        !          7524:   Documentation on Unix commands, system calls and libraries can be
        !          7525: obtained with the @kbd{M-x manual-entry} command.  This reads a topic as an
        !          7526: argument, and displays the text on that topic from the Unix manual.
        !          7527: @code{manual-entry} always searches all 8 sections of the manual, and
        !          7528: concatenates all the entries that are found.  For example, the topic
        !          7529: @samp{termcap} finds the description of the termcap library from section 3,
        !          7530: followed by the description of the termcap data base from section 5.
        !          7531: 
        !          7532: @node Change Log, Tags, Documentation, Programs
        !          7533: @section Change Logs
        !          7534: 
        !          7535: @cindex change log
        !          7536: @findex add-change-log-entry
        !          7537:   The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record
        !          7538: of when and why you have changed a program.  It assumes that you have a
        !          7539: file in which you write a chronological sequence of entries describing
        !          7540: individual changes.  The default is to store the change entries in a file
        !          7541: called @file{ChangeLog} in the same directory as the file you are editing.
        !          7542: The same @file{ChangeLog} file therefore records changes for all the files
        !          7543: in the directory.
        !          7544: 
        !          7545:   A change log entry starts with a header line that contains your name and
        !          7546: the current date.  Aside from these header lines, every line in the change
        !          7547: log starts with a tab.  One entry can describe several changes; each change
        !          7548: starts with a line starting with a tab and a star.  @kbd{M-x add-change-log-entry}
        !          7549: visits the change log file and creates a new entry unless the most recent
        !          7550: entry is for today's date and your name.  In either case, it adds a new
        !          7551: line to start the description of another change just after the header line
        !          7552: of the entry.  When @kbd{M-x add-change-log-entry} is finished, all is
        !          7553: prepared for you to edit in the description of what you changed and how.
        !          7554: You must then save the change log file yourself.
        !          7555: 
        !          7556:   The change log file is always visited in Indented Text mode, which means
        !          7557: that @key{LFD} and auto-filling indent each new line like the previous
        !          7558: line.  This is convenient for entering the contents of an entry, which must
        !          7559: all be indented.  @xref{Text Mode}.
        !          7560: 
        !          7561:   Here is an example of the formatting conventions used in the change log
        !          7562: for Emacs:
        !          7563: 
        !          7564: @smallexample
        !          7565: Wed Jun 26 19:29:32 1985  Richard M. Stallman  (rms at mit-prep)
        !          7566: 
        !          7567:         * xdisp.c (try_window_id):
        !          7568:         If C-k is done at end of next-to-last line,
        !          7569:         this fn updates window_end_vpos and cannot leave
        !          7570:         window_end_pos nonnegative (it is zero, in fact).
        !          7571:         If display is preempted before lines are output,
        !          7572:         this is inconsistent.  Fix by setting
        !          7573:         blank_end_of_window to nonzero.
        !          7574: 
        !          7575: Tue Jun 25 05:25:33 1985  Richard M. Stallman  (rms at mit-prep)
        !          7576: 
        !          7577:         * cmds.c (Fnewline):
        !          7578:         Call the auto fill hook if appropriate.
        !          7579: 
        !          7580:         * xdisp.c (try_window_id):
        !          7581:         If point is found by compute_motion after xp, record that
        !          7582:         permanently.  If display_text_line sets point position wrong
        !          7583:         (case where line is killed, point is at eob and that line is
        !          7584:         not displayed), detect and set it again in final compute_motion.
        !          7585: @end smallexample
        !          7586: 
        !          7587: @node Tags,, Change Log, Programs
        !          7588: @section Tag Tables
        !          7589: @cindex tag table
        !          7590: 
        !          7591:   A @dfn{tag table} is a description of how a multi-file program is broken
        !          7592: up into files.  It lists the names of the component files and the names and
        !          7593: positions of the functions in each file.  Grouping the related files makes
        !          7594: it possible to search or replace through all the files with one command.
        !          7595: Recording the function names and positions makes possible the @kbd{Meta-.}
        !          7596: command which you can use to find the definition of a function without
        !          7597: having to know which of the files it is in.
        !          7598: 
        !          7599:   Tag tables are stored in files called @dfn{tag table files}.  The
        !          7600: conventional name for a tag table file is @code{TAGS}.
        !          7601: 
        !          7602:   Each entry in the tag table records the name of one tag, the name of the
        !          7603: file that the tag is defined in (implicitly), and the position in that file
        !          7604: of the tag's definition.
        !          7605: 
        !          7606:   Just what names from the described files are recorded in the tag table
        !          7607: depends on the programming language of the described file.  They normally
        !          7608: include all functions and subroutines, and may also include global
        !          7609: variables, data types, and anything else convenient.  In any case, each
        !          7610: name recorded is called a @dfn{tag}.
        !          7611: 
        !          7612:   In Lisp code, any function defined with @code{defun}, any variable
        !          7613: defined with @code{defvar} or @code{defconst}, and in general the first
        !          7614: argument of any expression that starts with @samp{(def} in column zero, is
        !          7615: a tag.
        !          7616: 
        !          7617:   In C code, any C function is a tag, and so is any typedef if @code{-t} is
        !          7618: specified when the tag table is constructed.
        !          7619: 
        !          7620:   In Fortran code, functions and subroutines are tags.
        !          7621: 
        !          7622: @subsection Creating Tag Tables
        !          7623: @cindex etags program
        !          7624: 
        !          7625:   The @code{etags} program is used to create a tag table file.  It knows
        !          7626: the syntax of C, Fortran and Emacs Lisp.  To use @code{etags}, type
        !          7627: 
        !          7628: @example
        !          7629: etags @var{inputfiles}@dots{}
        !          7630: @end example
        !          7631: 
        !          7632: @noindent
        !          7633: as a shell command.  It reads the specified files and writes a tag table
        !          7634: named @code{TAGS} in the current working directory.  @code{etags}
        !          7635: recognizes the language used in an input file based on its file name and
        !          7636: contents; there are no switches for specifying the language.  The @code{-t}
        !          7637: switch tells @code{etags} to record typedefs in C code as tags.
        !          7638: 
        !          7639:   If the tag table data become outdated due to changes in the files
        !          7640: described in the table, the way to update the tag table is the same way it
        !          7641: was made in the first place.  It is not necessary to do this often.
        !          7642: 
        !          7643:   If the tag table fails to record a tag, or records it for the wrong file,
        !          7644: then Emacs cannot possibly find its definition.  However, if the position
        !          7645: recorded in the tag table becomes a little bit wrong (due to some editing
        !          7646: in the file that the tag definition is in), the only consequence is to slow
        !          7647: down finding the tag slightly.  Even if the stored position is very wrong,
        !          7648: Emacs will still find the tag, but it must search the entire file for it.
        !          7649: 
        !          7650:   So you should update a tag table when you define new tags that you want
        !          7651: to have listed, or when you move tag definitions from one file to another,
        !          7652: or when changes become substantial.  Normally there is no need to update
        !          7653: the tag table after each edit, or even every day.
        !          7654: 
        !          7655: @subsection Selecting a Tag Table
        !          7656: 
        !          7657: @vindex tags-file-name
        !          7658: @findex visit-tags-table
        !          7659:   Emacs has at any time one @dfn{selected} tag table, and all the commands
        !          7660: for working with tag tables use the selected one.  To select a tag table,
        !          7661: type @kbd{M-x visit-tags-table}, which reads the tag table file name as an
        !          7662: argument.  The name @code{TAGS} in the default directory is used as the
        !          7663: default file name.
        !          7664: 
        !          7665:   All this command does is store the file name in the variable
        !          7666: @code{tags-file-name}.  Emacs does not actually read in the tag table
        !          7667: contents until you try to use them.  Setting this variable yourself is just
        !          7668: as good as using @code{visit-tags-table}.  The variable's initial value is
        !          7669: @code{nil}; this value tells all the commands for working with tag tables
        !          7670: that they must ask for a tag table file name to use.
        !          7671: 
        !          7672: @subsection Finding a Tag
        !          7673: 
        !          7674:   The most important thing that a tag table enables you to do is to find
        !          7675: the definition of a specific tag.
        !          7676: 
        !          7677: @table @kbd
        !          7678: @item M-.@: @var{tag}
        !          7679: Find first definition of @var{tag} (@code{find-tag}).
        !          7680: @item C-u M-.
        !          7681: Find next alternate definition of last tag specified.
        !          7682: @item C-x 4 .@: @var{tag}
        !          7683: Find first definition of @var{tag}, but display it in another window
        !          7684: (@code{find-tag-other-window}).
        !          7685: @end table
        !          7686: 
        !          7687: @kindex M-.
        !          7688: @findex find-tag
        !          7689:   @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of a
        !          7690: specified tag.  It searches through the tag table for that tag, as a
        !          7691: string, and then uses the tag table info to determine the file that the
        !          7692: definition is in and the approximate character position in the file of the
        !          7693: definition.  Then @code{find-tag} visits that file, moves point to the
        !          7694: approximate character position, and starts searching ever-increasing
        !          7695: distances away for the the text that should appear at the beginning of the
        !          7696: definition.
        !          7697: 
        !          7698:   If an empty argument is given (just type @key{RET}), the sexp in the
        !          7699: buffer before or around point is used as the name of the tag to find.
        !          7700: @xref{Lists}, for info on sexps.
        !          7701: 
        !          7702:   The argument to @code{find-tag} need not be the whole tag name; it can be
        !          7703: a substring of a tag name.  However, there can be many tag names containing
        !          7704: the substring you specify.  Since @code{find-tag} works by searching the
        !          7705: text of the tag table, it finds the first tag in the table that the
        !          7706: specified substring appears in.  The way to find other tags that match the
        !          7707: substring is to give @code{find-tag} a numeric argument, as in @kbd{M-0 M-.};
        !          7708: this does not read a tag name, but continues searching the tag table's text
        !          7709: for another tag containing the same substring last used.
        !          7710: 
        !          7711: @kindex C-x 4 .
        !          7712: @findex find-tag-other-window
        !          7713:   Like most commands that can switch buffers, @code{find-tag} has another
        !          7714: similar command that displays the new buffer in another window.  @kbd{C-x 4
        !          7715: .}@: invokes the function @code{find-tag-other-window}.
        !          7716: 
        !          7717: @subsection Searching and Replacing with Tag Tables
        !          7718: 
        !          7719:   The commands in this section visit and search all the files listed in the
        !          7720: selected tag table, one by one.
        !          7721: 
        !          7722: @table @kbd
        !          7723: @item M-x tags-search
        !          7724: Search for the specified regexp through the files in the selected tag
        !          7725: table.
        !          7726: @item M-x tags-query-replace
        !          7727: Perform a @code{query-replace} on each file in the selected tag table.
        !          7728: @item M-,
        !          7729: Restart one of the commands above, from the current location of point
        !          7730: (@code{tags-loop-continue}).
        !          7731: @end table
        !          7732: 
        !          7733: @findex tags-search
        !          7734:   @kbd{M-x tags-search} reads a regexp using the minibuffer, then visits
        !          7735: the files of the selected tag table one by one, and searches through each
        !          7736: one for that regexp.  As soon as an occurrence is found, @code{tags-search}
        !          7737: returns.
        !          7738: 
        !          7739: @kindex M-,
        !          7740: @findex tags-loop-continue
        !          7741:   Having found one match, you probably want to find all the rest.  To find
        !          7742: one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
        !          7743: @code{tags-search}.  This searches the rest of the current buffer, followed
        !          7744: by the remaining files of the tag table.
        !          7745: 
        !          7746: @findex tags-query-replace
        !          7747:   @kbd{M-x tags-query-replace} performs a single @code{query-replace}
        !          7748: through all the files in the tag table.  It reads a string to search for
        !          7749: and a string to replace with, just like ordinary @kbd{M-x query-replace}.
        !          7750: It searches much like @kbd{M-x tags-search} but repeatedly, processing
        !          7751: matches according to your input.  @xref{Replace}, for more information on
        !          7752: @code{query-replace}.@refill
        !          7753: 
        !          7754:   It is possible to get through all the files in the tag table with a
        !          7755: single invocation of @kbd{M-x tags-query-replace}.  But since any
        !          7756: unrecognized character causes the command to exit, you may need to continue
        !          7757: where you left off.  @kbd{M-,} can be used for this.  It resumes the last
        !          7758: tags search or replace command that you did.
        !          7759: 
        !          7760:   It may have struck you that @code{tags-search} is a lot like @code{grep}.
        !          7761: You can also run @code{grep} itself as an inferior of Emacs and have Emacs
        !          7762: show you the matching lines one by one.  This works mostly the same as
        !          7763: running a compilation and having Emacs show you where the errors were.
        !          7764: @xref{Compilation}.
        !          7765: 
        !          7766: @subsection Stepping Through a Tag Table
        !          7767: @findex next-file
        !          7768: 
        !          7769:   If you wish to process all the files in the selected tag table, but
        !          7770: @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} in particular are not what
        !          7771: you want, you can use @kbd{M-x next-file}.
        !          7772: 
        !          7773: @table @kbd
        !          7774: @item C-u M-x next-file
        !          7775: With a numeric argument, regardless of its value, visit the first
        !          7776: file in the tag table, and prepare to advance sequentially by files.
        !          7777: @item M-x next-file
        !          7778: Visit the next file in the selected tag table.
        !          7779: @end table
        !          7780: 
        !          7781: @subsection Tag Table Inquiries
        !          7782: 
        !          7783: @table @kbd
        !          7784: @item M-x list-tags
        !          7785: Display a list of the tags defined in a specific program file.
        !          7786: @item M-x tags-apropos
        !          7787: Display a list of all tags matching a specified regexp.
        !          7788: @end table
        !          7789: 
        !          7790: @findex list-tags
        !          7791:   @kbd{M-x list-tags} reads the name of one of the files described by the
        !          7792: selected tag table, and displays a list of all the tags defined in that
        !          7793: file.  The ``file name'' argument is really just a string to compare
        !          7794: against the names recorded in the tag table; it is read as a string rather
        !          7795: than as a file name.  Therefore, completion and defaulting are not
        !          7796: available, and you must enter the string the same way it appears in the tag
        !          7797: table.  Do not include a directory as part of the file name unless the file
        !          7798: name recorded in the tag table includes a directory.
        !          7799: 
        !          7800: @findex tags-apropos
        !          7801:   @kbd{M-x tags-apropos} is like @code{apropos} for tags.  It reads a regexp,
        !          7802: then finds all the tags in the selected tag table whose entries match that
        !          7803: regexp, and displays the tag names found.
        !          7804: 
        !          7805: @node Running, Abbrevs, Programs, Top
        !          7806: @chapter Compiling and Testing Programs
        !          7807: 
        !          7808:   The previous chapter discusses the Emacs commands that are useful for
        !          7809: making changes in programs.  This chapter deals with commands that assist
        !          7810: in the larger process of developing and maintaining programs.
        !          7811: 
        !          7812: @menu
        !          7813: * Compilation::        Compiling programs in languages other than Lisp
        !          7814:                         (C, Pascal, etc.)
        !          7815: * Modes: Lisp Modes.   Various modes for editing Lisp programs, with
        !          7816:                        different facilities for running the Lisp programs.
        !          7817: * Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.
        !          7818: * Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
        !          7819: * Eval: Lisp Eval.     Executing a single Lisp expression in Emacs.
        !          7820: * Debug: Lisp Debug.   Debugging Lisp programs running in Emacs.
        !          7821: * External Lisp::      Communicating through Emacs with a separate Lisp.
        !          7822: @end menu
        !          7823: 
        !          7824: @node Compilation, Lisp Modes, Running, Running
        !          7825: @section Running `make', or Compilers Generally
        !          7826: @cindex inferior process
        !          7827: @cindex make
        !          7828: @cindex compilation errors
        !          7829: @cindex error log
        !          7830: 
        !          7831:   Emacs can run compilers for noninteractive languages such as C and
        !          7832: Fortran as inferior processes, feeding the error log into an Emacs buffer.
        !          7833: It can also parse the error messages and visit the files in which errors
        !          7834: are found, moving point right to the line where the error occurred.
        !          7835: 
        !          7836: @table @kbd
        !          7837: @item M-x compile
        !          7838: Run a compiler asynchronously under Emacs, with error messages to
        !          7839: @samp{*compilation*} buffer.
        !          7840: @item M-x grep
        !          7841: Run @code{grep} asynchronously under Emacs, with matching lines
        !          7842: listed in the @samp{*compilation*} buffer.
        !          7843: @item M-x kill-compiler
        !          7844: @itemx M-x kill-grep
        !          7845: Kill the running compilation or @code{grep} subprocess.
        !          7846: @item C-x `
        !          7847: Visit the locus of the next compiler error message or @code{grep} match.
        !          7848: @end table
        !          7849: 
        !          7850: @findex compile
        !          7851:   To run @code{make} or another compiler, do @kbd{M-x compile}.  This command
        !          7852: reads a shell command line using the minibuffer, and then executes the
        !          7853: specified command line in an inferior shell with output going to the buffer
        !          7854: named @samp{*compilation*}.  The current buffer's default directory is used
        !          7855: as the working directory for the execution of the command; normally,
        !          7856: therefore, the makefile comes from this directory.
        !          7857: 
        !          7858: @vindex compile-command
        !          7859:   When the shell command line is read, the minibuffer appears containing a
        !          7860: default command line, which is the command you used the last time you did
        !          7861: @kbd{M-x compile}.  If you type just @key{RET}, the same command line is used
        !          7862: again.  The first @kbd{M-x compile} provides @code{make -k} as the default.
        !          7863: The default is taken from the variable @code{compile-command}; if the
        !          7864: appropriate compilation command for a file is something other than
        !          7865: @code{make -k}, it can be useful to have the file specify a local value for
        !          7866: @code{compile-command} (@pxref{File Variables}).
        !          7867: 
        !          7868:   Starting a compilation causes the buffer @samp{*compilation*} to be
        !          7869: displayed in another window but not selected.  Its mode line tells you
        !          7870: whether compilation is finished, with the word @samp{run} or @samp{exit} inside
        !          7871: the parentheses.  You do not have to keep this buffer visible; compilation
        !          7872: continues in any case.
        !          7873: 
        !          7874: @findex kill-compilation
        !          7875:   To kill the compilation process, do @kbd{M-x kill-compilation}.  You will
        !          7876: see that the mode line of the @samp{*compilation*} buffer changes to say
        !          7877: @samp{signal} instead of @samp{run}.  Starting a new compilation also kills
        !          7878: any running compilation, as only one can exist at any time.  However, this
        !          7879: requires confirmation before actually killing a compilation that is
        !          7880: running.@refill
        !          7881: 
        !          7882: @kindex C-x `
        !          7883: @findex next-error
        !          7884:   To parse the compiler error messages, type @kbd{C-x `} (@code{next-error}).  The
        !          7885: character following the @kbd{C-x} is the grave accent, not the single
        !          7886: quote.  This command displays the buffer @samp{*compilation*} in one window
        !          7887: and the buffer in which the next error occurred in another window.  Point
        !          7888: in that buffer is moved to the line where the error was found.  The
        !          7889: corresponding error message is scrolled to the top of the window in which
        !          7890: @samp{*compilation*} is displayed.
        !          7891: 
        !          7892:   The first time @kbd{C-x `} is used, after the start of a compilation, it
        !          7893: parses all the error messages, visits all the files that have error
        !          7894: messages, and makes markers pointing at the lines that the error messages
        !          7895: refer to.  Then it moves to the first error message location.  Subsequent
        !          7896: uses of @kbd{C-x `} advance down the data set up by the first use.  When
        !          7897: the preparsed error messages are exhausted, the next @kbd{C-x `} checks for
        !          7898: any more error messages that have come in; this is useful if you start
        !          7899: editing the compiler errors while the compilation is still going on.  If no
        !          7900: more error messages have come in, @kbd{C-x `} reports an error.
        !          7901: 
        !          7902:   @kbd{C-u C-x `} discards the preparsed error message data and parses the
        !          7903: @samp{*compilation*} buffer over again, then displaying the first error.
        !          7904: This way, you can process the same set of errors again.
        !          7905: 
        !          7906:   Instead of running a compiler, you can run @code{grep} and see the lines
        !          7907: on which matches were found.  To do this, type @kbd{M-x grep} with an argument
        !          7908: line that contains the same arguments you would give @code{grep} when running
        !          7909: it normally: a @code{grep}-style regexp (usually in doublequotes to quote
        !          7910: the shell's special characters) followed by filenames which may use wildcards.
        !          7911: The output from @code{grep} goes in the @samp{*compilation*} buffer and the
        !          7912: lines that matched can be found with @kbd{C-x `} as if they were compilation
        !          7913: errors.
        !          7914: 
        !          7915:   Note: a shell is used to run the compile command, but the shell is told
        !          7916: that it should be noninteractive.  This means in particular that the shell
        !          7917: starts up with no prompt.  If you find your usual shell prompt making an
        !          7918: unsightly appearance in the @samp{*compilation*} buffer, it means you have
        !          7919: made a mistake in your shell's init file (@file{.cshrc} or @file{.shrc} or
        !          7920: @dots{}) by setting the prompt unconditionally.  The shell init file should
        !          7921: set the prompt only if there already is a prompt.  In @code{csh}, here is
        !          7922: how to do it:
        !          7923: 
        !          7924: @example
        !          7925: if ($?prompt) set prompt = ... 
        !          7926: @end example
        !          7927: 
        !          7928: @node Lisp Modes, Lisp Libraries, Compilation, Running
        !          7929: @section Major Modes for Lisp
        !          7930: 
        !          7931:   Emacs has four different major modes for Lisp.  They are the same in
        !          7932: terms of editing commands, but differ in the commands for executing Lisp
        !          7933: expressions.
        !          7934: 
        !          7935: @table @asis
        !          7936: @item Emacs-Lisp mode
        !          7937: The mode for editing source files of programs to run in Emacs Lisp.
        !          7938: This mode defines @kbd{C-M-x} to evaluate the current defun.
        !          7939: @xref{Lisp Libraries}.
        !          7940: @item Lisp Interaction mode
        !          7941: The mode for an interactive session with Emacs Lisp.  It defines
        !          7942: @key{LFD} to evaluate the sexp before point and insert its value in the
        !          7943: buffer.  @xref{Lisp Interaction}.
        !          7944: @item Lisp mode
        !          7945: The mode for editing source files of programs that run in Lisps other
        !          7946: than Emacs Lisp.  This mode defines @kbd{C-M-x} to send the current defun
        !          7947: to an inferior Lisp process.  @xref{External Lisp}.
        !          7948: @item Inferior Lisp mode
        !          7949: The mode for an interactive session with an inferior Lisp process.
        !          7950: This mode combines the special features of Lisp mode and Shell mode
        !          7951: (@pxref{Shell}).
        !          7952: @end table
        !          7953: 
        !          7954: @node Lisp Libraries, Lisp Eval, Lisp Modes, Running
        !          7955: @section Libraries of Lisp Code for Emacs
        !          7956: @cindex libraries
        !          7957: @cindex loading Lisp code
        !          7958: 
        !          7959:   Lisp code for Emacs editing commands is stored in files whose names
        !          7960: conventionally end in @file{.el}.  This ending tells Emacs to edit them in
        !          7961: Emacs-Lisp mode, so you can use the @kbd{C-M-x} command described in the
        !          7962: following section to install changed functions.
        !          7963: 
        !          7964: @findex load
        !          7965:   Only the maintainers of such a file will want to edit its contents or
        !          7966: evaluate text from it, but every user must be able to load the file.  This
        !          7967: is done with @kbd{M-x load}.
        !          7968: 
        !          7969:   @kbd{M-x load} reads a file name using the minibuffer and executes the
        !          7970: specified file as Lisp code.  But it has an important difference from all
        !          7971: other Emacs commands that read file names: it searches a sequence of
        !          7972: directories, and tries three file names in each directory.
        !          7973: 
        !          7974:   Because normally one does not want the argument to @code{load} to contain
        !          7975: an explicit directory name, the usual mechanism for reading file names
        !          7976: cannot be used, and therefore file name completion is not available.
        !          7977: (Which directory would it complete in, anyway?)
        !          7978: 
        !          7979:   The argument you give to @kbd{M-x load} is usually not the full file
        !          7980: name.  Usually you omit the @file{.el} that the file name ends in.
        !          7981: @kbd{M-x load} tries three file names in each directory: first, the name
        !          7982: you specified; second, that name with @file{.elc} appended; third, that
        !          7983: name with @file{.el} appended.  A @file{.elc} file would be the result of
        !          7984: compiling the Lisp file into byte code; it is loaded if possible in
        !          7985: preference to the Lisp file itself because the compiled file will load and
        !          7986: run faster.
        !          7987: 
        !          7988: @vindex load-path
        !          7989:   The sequence of directories searched by @kbd{M-x load} is specified by
        !          7990: the variable @code{load-path}, a list of strings that are directory names.
        !          7991: Normally the first element of this list is @code{nil}, which means to
        !          7992: search the current default directory at that point; the remaining elements
        !          7993: are the names of the directories in which the Lisp code of Emacs itself is
        !          7994: stored.  Therefore, you can load an installed Emacs library without having
        !          7995: to specify a directory name.
        !          7996: 
        !          7997:   Often you do not have to run the @code{load} command yourself, because
        !          7998: the commands in a library have permanent definitions to @dfn{autoload}
        !          7999: that library.  Running any of those commands causes @code{load} to be
        !          8000: called to load the library; this replaces the autoload definitions with
        !          8001: the real ones from the library.
        !          8002: 
        !          8003:   If autoloading a file does not finish, either because of an error or
        !          8004: because of a @kbd{C-g} quit, all function definitions made by the file are
        !          8005: undone automatically.  So are any calls to @code{provide}.  As a consequence,
        !          8006: if you use one of the autoloadable commands again, the entire file will be
        !          8007: loaded a second time.  This prevents problems where the command is no
        !          8008: longer autoloading but it works wrong because not all the file was loaded.
        !          8009: Function definitions are undone only for autoloading; explicit calls to
        !          8010: @code{load} do not undo anything if loading is not completed.
        !          8011: 
        !          8012: @findex byte-compile-file
        !          8013:   The way to make a byte-code compiled file from an Emacs-Lisp source file
        !          8014: is with @kbd{M-x byte-compile-file}.  The default argument for this
        !          8015: function is the file visited in the current buffer.  It reads the specified
        !          8016: file, compiles it into byte code, and writes an output file whose name is
        !          8017: made by appending @file{c} to the input file name.  Thus, the file
        !          8018: @file{rmail.el} would be compiled into @file{rmail.elc}.
        !          8019: 
        !          8020: @findex byte-recompile-directory
        !          8021:   To recompile the changed Lisp files in a directory, use @kbd{M-x
        !          8022: byte-recompile-directory}.  Specify just the directory name as an argument.
        !          8023: Each @file{.el} file that has been byte-compiled before is byte-compiled
        !          8024: again if it has changed since the previous compilation.  A numeric argument
        !          8025: to this command tells it to offer to compile each @file{.el} file that has
        !          8026: not already been compiled.  You must answer @kbd{y} or @kbd{n} to each
        !          8027: offer.
        !          8028: 
        !          8029: @findex batch-byte-compile
        !          8030:   Emacs can be invoked noninteractively from the shell to do byte compilation
        !          8031: with the aid of the function @code{batch-byte-compile}.  In this case,
        !          8032: the files to be compiled are specified with command-line arguments.
        !          8033: Use a shell command of the form
        !          8034: 
        !          8035: @example
        !          8036: emacs -batch -f batch-byte-compile @var{files}...
        !          8037: @end example
        !          8038: 
        !          8039:   Directory names may also be given as arguments;
        !          8040: @code{byte-recompile-directory} is invoked (in effect) on each such directory.
        !          8041: @code{batch-byte-compile} uses all the remaining command-line arguments as
        !          8042: file or directory names, then kills the Emacs process.
        !          8043: 
        !          8044: @cindex mocklisp
        !          8045:   GNU Emacs can run Mocklisp files by converting them to Emacs Lisp first.
        !          8046: To convert a Mocklisp file, visit it and then type @kbd{M-x
        !          8047: convert-mocklisp-buffer}.  Then save the resulting buffer of Lisp file in a
        !          8048: file whose name ends in @file{.el} and use the new file as a Lisp library.
        !          8049: 
        !          8050: @node Lisp Eval, Lisp Debug, Lisp Libraries, Running
        !          8051: @section Evaluating Emacs-Lisp Expressions
        !          8052: @cindex Emacs-Lisp mode
        !          8053: 
        !          8054: @findex emacs-lisp-mode
        !          8055:   Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp
        !          8056: mode; normally this will happen based on the file name that ends in
        !          8057: @file{.el}.  By contrast, Lisp mode itself is used for editing Lisp programs
        !          8058: intended for other Lisp systems.  Emacs-Lisp mode can be selected with the
        !          8059: command @kbd{M-x emacs-lisp-mode}.
        !          8060: 
        !          8061:   For testing of Lisp programs to run in Emacs, it is useful to be able to
        !          8062: evaluate part of the program as it is found in the Emacs buffer.  For
        !          8063: example, after changing the text of a Lisp function definition, evaluating
        !          8064: the definition installs the change for future calls to the function.
        !          8065: Evaluation of Lisp expressions is also useful in any kind of editing task
        !          8066: for invoking noninteractive functions (functions that are not commands).
        !          8067: 
        !          8068: @table @kbd
        !          8069: @item M-@key{ESC}
        !          8070: Read a Lisp expression in the minibuffer, evaluate it, and print the
        !          8071: value in the minibuffer (@code{eval-expression}).
        !          8072: @item C-x C-e
        !          8073: Evaluate the Lisp expression before point, and print the value in the
        !          8074: minibuffer (@code{eval-last-sexp}).
        !          8075: @item C-M-x
        !          8076: Evaluate the defun containing or after point, and print the value in
        !          8077: the minibuffer (@code{eval-defun}).
        !          8078: @item M-x eval-region
        !          8079: Evaluate all the Lisp expressions in the region.
        !          8080: @item M-x eval-current-buffer
        !          8081: Evaluate all the Lisp expressions in the buffer.
        !          8082: @end table
        !          8083: 
        !          8084: @kindex M-ESC
        !          8085: @findex eval-expression
        !          8086:   @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command for evaluating
        !          8087: a Lisp expression interactively.  It reads the expression using the
        !          8088: minibuffer, so you can execute any expression on a buffer regardless of
        !          8089: what the buffer contains.  When the expression is evaluated, the current
        !          8090: buffer is once again the buffer that was current when @kbd{M-@key{ESC}} was
        !          8091: typed.
        !          8092: 
        !          8093:   @kbd{M-@key{ESC}} can easily confuse users who do not understand it,
        !          8094: especially on keyboards with autorepeat where it can result from holding
        !          8095: down the @key{ESC} key for too long.  Therefore, @code{eval-expression} is
        !          8096: normally a disabled command.  Attempting to use this command asks for
        !          8097: confirmation and gives you the option of enabling it; once you enable the
        !          8098: command, confirmation will no longer be required for it.
        !          8099: @xref{Disabling}.@refill
        !          8100: 
        !          8101: @kindex C-M-x
        !          8102: @findex eval-defun
        !          8103:   In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function @code{eval-defun},
        !          8104: which parses the defun containing or following point as a Lisp expression
        !          8105: and evaluates it.  The value is printed in the echo area.  This command is
        !          8106: convenient for installing in the Lisp environment changes that you have
        !          8107: just made in the text of a function definition.
        !          8108: 
        !          8109: @kindex C-x C-e
        !          8110: @findex eval-last-sexp
        !          8111:   The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job
        !          8112: but is available in all major modes, not just Emacs-Lisp mode.  It finds
        !          8113: the sexp before point, reads it as a Lisp expression, evaluates it, and
        !          8114: prints the value in the echo area.  It is sometimes useful to type in an
        !          8115: expression and then, with point still after it, type @kbd{C-x C-e}.
        !          8116: 
        !          8117:   If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it prints the value
        !          8118: by insertion into the current buffer at point, rather than in the echo
        !          8119: area.  The argument value does not matter.
        !          8120: 
        !          8121: @findex eval-region
        !          8122: @findex eval-current-buffer
        !          8123:   The most general command for evaluating Lisp expressions from a buffer is
        !          8124: @code{eval-region}.  @kbd{M-x eval-region} parses the text of the region as one or
        !          8125: more Lisp expressions, evaluating them one by one.  @kbd{M-x eval-current-buffer}
        !          8126: is similar but evaluates the entire buffer.  This is a reasonable way to
        !          8127: install the contents of a file of Lisp code that you are just ready to
        !          8128: test.  After finding and fixing a bug, use @kbd{C-M-x} on each function
        !          8129: that you change, to keep the Lisp world in step with the source file.
        !          8130: 
        !          8131: @node Lisp Debug, Lisp Interaction, Lisp Eval, Running
        !          8132: @section The Lisp Debugger
        !          8133: @cindex debugger
        !          8134: 
        !          8135: @vindex debug-on-error
        !          8136: @vindex debug-on-quit
        !          8137:   GNU Emacs contains a debugger for Lisp programs executing inside it.
        !          8138: This debugger is normally not used; many commands frequently get Lisp
        !          8139: errors when invoked in inappropriate contexts (such as @kbd{C-f} at the end
        !          8140: of the buffer) and it would be very unpleasant for that to enter a special
        !          8141: debugging mode.  When you want to make Lisp errors invoke the debugger, you
        !          8142: must set the variable @code{debug-on-error} to non-@code{nil}.  Quitting
        !          8143: with @kbd{C-g} is not considered an error, and @code{debug-on-error} has no
        !          8144: effect on the handling of @kbd{C-g}.  However, if you set
        !          8145: @code{debug-on-quit} non-@code{nil}, @kbd{C-g} will invoke the debugger.
        !          8146: This can be useful for debugging an infinite loop; type @kbd{C-g} once the
        !          8147: loop has had time to reach its steady state.  @code{debug-on-quit} has no
        !          8148: effect on errors.@refill
        !          8149: 
        !          8150: @findex debug-on-entry
        !          8151: @findex cancel-debug-on-entry
        !          8152: @findex debug
        !          8153:   You can also cause the debugger to be entered when a specified function
        !          8154: is called, or at a particular place in Lisp code.  Use @kbd{M-x
        !          8155: debug-on-entry} with argument @var{fun-name} to cause function
        !          8156: @var{fun-name} to enter the debugger as soon as it is called.  Use
        !          8157: @kbd{M-x cancel-debug-on-entry} to make the function stop entering the
        !          8158: debugger when called.  (Redefining the function also does this.)  To enter
        !          8159: the debugger from some other place in Lisp code, you must insert the
        !          8160: expression @code{(debug)} there and install the changed code with
        !          8161: @kbd{C-M-x}.  @xref{Lisp Eval}.@refill
        !          8162: 
        !          8163:   When the debugger is entered, it displays the previously selected buffer
        !          8164: in one window and a buffer named @samp{*Backtrace*} in another window.  The
        !          8165: backtrace buffer contains one line for each level of Lisp function
        !          8166: execution currently going on.  At the beginning of this buffer is a message
        !          8167: describing the reason that the debugger was invoked (such as, what error
        !          8168: message if it was invoked due to an error).
        !          8169: 
        !          8170:   The backtrace buffer is read-only, and is in a special major mode,
        !          8171: Backtrace mode, in which letters are defined as debugger commands.  The
        !          8172: usual Emacs editing commands are available; you can switch windows to
        !          8173: examine the buffer that was being edited at the time of the error, and you
        !          8174: can also switch buffers, visit files, and do any other sort of editing.
        !          8175: However, the debugger is a recursive editing level (@pxref{Recursive Edit})
        !          8176: and it is wise to go back to the backtrace buffer and exit the debugger
        !          8177: officially when you don't want to use it any more.  Exiting the debugger
        !          8178: kills the backtrace buffer.
        !          8179: 
        !          8180: @cindex current stack frame
        !          8181:   The contents of the backtrace buffer show you the functions that are
        !          8182: executing and the arguments that were given to them.  It has the additional
        !          8183: purpose of allowing you to specify a stack frame by moving point to the line
        !          8184: describing that frame.  The frame whose line point is on is considered the
        !          8185: @dfn{current frame}.  Some of the debugger commands operate on the current
        !          8186: frame.  Debugger commands are mainly used for stepping through code an
        !          8187: expression at a time.  Here is a list of them.
        !          8188: 
        !          8189: @table @kbd
        !          8190: @item c
        !          8191: Exit the debugger and continue execution.  In most cases, execution of the
        !          8192: program continues as if the debugger had never been entered (aside from the
        !          8193: effect of any variables or data structures you may have changed while
        !          8194: inside the debugger).  This includes entry to the debugger due to function
        !          8195: entry or exit, explicit invocation, quitting or certain errors.  Most
        !          8196: errors cannot be continued; trying to continue one of them causes the same
        !          8197: error to occur again.
        !          8198: @item d
        !          8199: Continue execution, but enter the debugger the next time a Lisp
        !          8200: function is called.  This allows you to step through the
        !          8201: subexpressions of an expression, seeing what values the subexpressions
        !          8202: compute and what else they do.
        !          8203: 
        !          8204: The stack frame made for the function call which enters the debugger
        !          8205: in this way will be flagged automatically for the debugger to be called
        !          8206: when the frame is exited.  You can use the @kbd{u} command to cancel
        !          8207: this flag.
        !          8208: @item b
        !          8209: Set up to enter the debugger when the current frame is exited.  Frames
        !          8210: that will invoke the debugger on exit are flagged with stars.
        !          8211: @item u
        !          8212: Don't enter the debugger when the current frame is exited.  This
        !          8213: cancels a @kbd{b} command on that frame.
        !          8214: @item e
        !          8215: Read a Lisp expression in the minibuffer, evaluate it, and print the
        !          8216: value in the echo area.  The same as the command @kbd{M-@key{ESC}},
        !          8217: except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}.
        !          8218: @item q
        !          8219: Terminate the program being debugged; return to top level Emacs
        !          8220: command execution.
        !          8221: 
        !          8222: If the debugger was entered due to a @kbd{C-g} but you really want
        !          8223: to quit, not to debug, use the @kbd{q} command.
        !          8224: @item r
        !          8225: Return a value from the debugger.  The value is computed by reading an
        !          8226: expression with the minibuffer and evaluating it.
        !          8227: 
        !          8228: The value returned by the debugger makes a difference when the debugger
        !          8229: was invoked due to exit from a Lisp call frame (as requested with @kbd{b});
        !          8230: then the value specified in the @kbd{r} command is used as the value of
        !          8231: that frame.
        !          8232: 
        !          8233: The debugger's return value also matters with many errors.  For example,
        !          8234: @code{wrong-type-argument} errors will use the debugger's return value
        !          8235: instead of the invalid argument; @code{no-catch} errors will use the
        !          8236: debugger value as a throw tag instead of the tag that was not found.
        !          8237: If an error was signaled by calling the Lisp function @code{signal},
        !          8238: the debugger's return value is returned as the value of @code{signal}.
        !          8239: @end table
        !          8240: 
        !          8241: @node Lisp Interaction, External Lisp, Lisp Debug, Running
        !          8242: @section Lisp Interaction Buffers
        !          8243: 
        !          8244:   The buffer @samp{*scratch*} which is selected when Emacs starts up is
        !          8245: provided for evaluating Lisp expressions interactively inside Emacs.  Both
        !          8246: the expressions you evaluate and their output goes in the buffer.
        !          8247: 
        !          8248:   The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
        !          8249: is the same as Emacs-Lisp mode except for one command, @key{LFD}.  In
        !          8250: Emacs-Lisp mode, @key{LFD} is an indentation command, as usual.  In Lisp
        !          8251: Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}.  This
        !          8252: function reads the Lisp expression before point, evaluates it, and inserts
        !          8253: the value in printed representation before point.
        !          8254: 
        !          8255:   Thus, the way to use the @samp{*scratch*} buffer is to insert Lisp expressions
        !          8256: at the end, ending each one with @key{LFD} so that it will be evaluated.
        !          8257: The result is a complete typescript of the expressions you have evaluated
        !          8258: and their values.
        !          8259: 
        !          8260: @findex lisp-interaction-mode
        !          8261:   The rationale for this feature is that Emacs must have a buffer when it
        !          8262: starts up, but that buffer is not useful for editing files since a new
        !          8263: buffer is made for every file that you visit.  The Lisp interpreter
        !          8264: typescript is the most useful thing I can think of for the initial buffer
        !          8265: to do.  @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp
        !          8266: Interaction mode.
        !          8267: 
        !          8268: @node External Lisp,, Lisp Interaction, Running
        !          8269: @section Running an External Lisp
        !          8270: 
        !          8271:   Emacs has facilities for running programs in other Lisp systems.  You can
        !          8272: run a Lisp process as an inferior of Emacs, and pass expressions to it to
        !          8273: be evaluated.  You can also pass changed function definitions directly from
        !          8274: the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
        !          8275: process.
        !          8276: 
        !          8277: @findex run-lisp
        !          8278:   To run an inferior Lisp process, type @kbd{M-x run-lisp}.  This runs the
        !          8279: program named @code{lisp}, the same program you would run by typing
        !          8280: @code{lisp} as a shell command, with both input and output going through an
        !          8281: Emacs buffer named @samp{*lisp*}.  That is to say, any ``terminal output''
        !          8282: from Lisp will go into the buffer, advancing point, and any ``terminal
        !          8283: input'' for Lisp comes from text in the buffer.  To give input to Lisp, go
        !          8284: to the end of the buffer and type the input, terminated by @key{RET}.  The
        !          8285: @samp{*lisp*} buffer is in Inferior Lisp mode, a mode which has all the
        !          8286: special characteristics of Lisp mode and Shell mode (@pxref{Shell}).
        !          8287: 
        !          8288: @findex lisp-mode
        !          8289:   For the source files of programs to run in external Lisps, use Lisp mode.
        !          8290: This mode can be selected with @kbd{M-x lisp-mode}, and is used automatically
        !          8291: for files whose names end in @file{.l} or @file{.lisp}, as most Lisp
        !          8292: systems usually expect.
        !          8293: 
        !          8294: @kindex C-M-x
        !          8295: @findex lisp-send-defun
        !          8296:   When you edit a function in a Lisp program you are running, the easiest
        !          8297: way to send the changed definition to the inferior Lisp process is the key
        !          8298: @kbd{C-M-x}.  In Lisp mode, this runs the function @code{lisp-send-defun},
        !          8299: which finds the defun around or following point and sends it as input to
        !          8300: the Lisp process.  (Emacs can send input to any inferior process regardless
        !          8301: of what buffer is current.)
        !          8302: 
        !          8303:   Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
        !          8304: to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
        !          8305: programs to be run in Emacs): in both modes it has the effect of installing
        !          8306: the function definition that point is in, but the way of doing so is
        !          8307: different according to where the relevant Lisp environment is found.
        !          8308: @xref{Lisp Modes}.
        !          8309: 
        !          8310: @node Abbrevs, Picture, Running, Top
        !          8311: @chapter Abbrevs
        !          8312: @cindex abbrevs
        !          8313: @cindex expansion (of abbrevs)
        !          8314: 
        !          8315:   An @dfn{abbrev} is a word which @dfn{expands}, if you insert it, into some
        !          8316: different text.  Abbrevs are defined by the user to expand in specific
        !          8317: ways.  For example, you might define @samp{foo} as an abbrev expanding to
        !          8318: @samp{find outer otter}.  With this abbrev defined, you would be able to
        !          8319: get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}.
        !          8320: 
        !          8321: @findex abbrev-mode
        !          8322: @vindex abbrev-mode
        !          8323:   Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
        !          8324: Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
        !          8325: but they do not expand until Abbrev mode is enabled again.  The command
        !          8326: @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
        !          8327: turns Abbrev mode on if the argument is positive, off otherwise.
        !          8328: @xref{Minor Modes}.  @code{abbrev-mode} is also a variable, local to each
        !          8329: buffer; Abbrev mode is on when the variable is non-@code{nil}.
        !          8330: 
        !          8331:   Abbrev definitions can be @dfn{mode-specific}---active only in one major
        !          8332: mode.  Abbrevs can also have @dfn{global} definitions that are active in
        !          8333: all major modes.  The same abbrev can have a global definition and various
        !          8334: mode-specific definitions for different major modes.  A mode specific
        !          8335: definition for the current major mode overrides a global definition.
        !          8336: 
        !          8337:   Abbrevs can be defined interactively during the editing session.  Lists
        !          8338: of abbrev definitions can also be saved in files and reloaded in later
        !          8339: sessions.  Some users keep extensive lists of abbrevs that they load in
        !          8340: every session.
        !          8341: 
        !          8342: @menu
        !          8343: * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
        !          8344: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
        !          8345: * Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
        !          8346: * Saving Abbrevs::    Saving the entire list of abbrevs for another session.
        !          8347: @end menu
        !          8348: 
        !          8349: @node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs
        !          8350: @section Defining Abbrevs
        !          8351: 
        !          8352: @table @kbd
        !          8353: @item C-x +
        !          8354: Define an abbrev to expand into some text before point
        !          8355: (@code{add-global-abbrev}).
        !          8356: @item C-x C-a
        !          8357: Similar, but define an abbrev available only in the current major mode
        !          8358: (@code{add-mode-abbrev}).
        !          8359: @item C-x -
        !          8360: Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
        !          8361: @item C-x C-h
        !          8362: Define a word in the buffer as a mode-specific abbrev
        !          8363: (@code{inverse-add-mode-abbrev}).
        !          8364: @item M-x kill-all-abbrevs
        !          8365: After this command, there are no abbrev definitions in effect.
        !          8366: @end table
        !          8367: 
        !          8368: @kindex C-x +
        !          8369: @findex add-global-abbrev
        !          8370:   The usual way to define an abbrev is to enter the text you want the
        !          8371: abbrev to expand to, position point after it, and type @kbd{C-x +}
        !          8372: (@code{add-global-abbrev}).  This reads the abbrev itself using the
        !          8373: minibuffer, and then defines it as an abbrev for one or more words before
        !          8374: point.  Use a numeric argument to say how many words before point should be
        !          8375: taken as the expansion.  For example, to define the abbrev @samp{foo} as
        !          8376: mentioned above, insert the text @samp{find outer otter} and then type
        !          8377: @kbd{C-u 3 C-x + f o o @key{RET}}.
        !          8378: 
        !          8379:   An argument of zero to @kbd{C-x +} means to use the contents of the
        !          8380: region as the expansion of the abbrev being defined.
        !          8381: 
        !          8382: @kindex C-x C-a
        !          8383: @findex add-mode-abbrev
        !          8384:   The command @kbd{C-x C-a} (@code{add-mode-abbrev}) is similar, but
        !          8385: defines a mode-specific abbrev.  Mode specific abbrevs are active only in a
        !          8386: particular major mode.  @kbd{C-x C-a} defines an abbrev for the major mode
        !          8387: in effect at the time @kbd{C-x C-a} is typed.  The arguments work the same
        !          8388: as for @kbd{C-x +}.
        !          8389: 
        !          8390: @kindex C-x -
        !          8391: @findex inverse-add-global-abbrev
        !          8392: @kindex C-x C-h
        !          8393: @findex inverse-add-mode-abbrev
        !          8394:   If the text of the abbrev you want is already in the buffer instead of
        !          8395: the expansion, use command @kbd{C-x -} (@code{inverse-add-global-abbrev})
        !          8396: instead of @kbd{C-x +}, or use @kbd{C-x C-h}
        !          8397: (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x C-a}.  These commands
        !          8398: are called ``inverse'' because they invert the meaning of the argument
        !          8399: found in the buffer and the argument read using the minibuffer.@refill
        !          8400: 
        !          8401:   To change the definition of an abbrev, just add the new definition.  You
        !          8402: will be asked to confirm if the abbrev has a prior definition.  To remove
        !          8403: an abbrev definition, give a negative argument to @kbd{C-x +} or @kbd{C-x
        !          8404: C-a}.  You must choose the command to specify whether to kill a global
        !          8405: definition or a mode-specific definition for the current mode, since those
        !          8406: two definitions are independent for one abbrev.
        !          8407: 
        !          8408: @findex kill-all-abbrevs
        !          8409:   @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there are.
        !          8410: 
        !          8411: @node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs
        !          8412: @section Controlling Abbrev Expansion
        !          8413: 
        !          8414:   An abbrev expands whenever it is present in the buffer just before point
        !          8415: and a self-inserting punctuation character (@key{SPC}, comma, etc.@:) is
        !          8416: typed.  Most often the way an abbrev is used is to insert the abbrev
        !          8417: followed by punctuation.
        !          8418: 
        !          8419: @vindex abbrev-all-caps
        !          8420:   Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
        !          8421: outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
        !          8422: @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
        !          8423: variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
        !          8424: of the two expansions).@refill
        !          8425: 
        !          8426:   These two commands are used to control abbrev expansion:
        !          8427: 
        !          8428: @table @kbd
        !          8429: @item M-'
        !          8430: Separate a prefix from a following abbrev to be expanded
        !          8431: (@code{abbrev-prefix-mark}).
        !          8432: @item M-x unexpand-abbrev
        !          8433: Undo last abbrev expansion.
        !          8434: @item M-x expand-region-abbrevs
        !          8435: Expand some or all abbrevs found in the region.
        !          8436: @end table
        !          8437: 
        !          8438: @kindex M-'
        !          8439: @findex abbrev-prefix-mark
        !          8440:   You may wish to expand an abbrev with a prefix attached; for example, if
        !          8441: @samp{cnst} expands into @samp{construction}, you might want to use it to
        !          8442: enter @samp{reconstruction}.  It does not work to type @kbd{recnst},
        !          8443: because that is not necessarily a defined abbrev.  What does work is to use
        !          8444: the command @kbd{M-'} (@code{abbrev-prefix-mark}) in between the prefix
        !          8445: @samp{re} and the abbrev @samp{cnst}.  First, insert @samp{re}.  Then type
        !          8446: @kbd{M-'}; this inserts a minus sign in the buffer to indicate that it has
        !          8447: done its work.  Then insert the abbrev @samp{cnst}; the buffer now contains
        !          8448: @samp{re-cnst}.  Now insert a punctuation character to expand the abbrev
        !          8449: @samp{cnst} into @samp{construction}.  The minus sign is deleted at this
        !          8450: point, because @kbd{M-'} left word for this to be done.  The resulting text
        !          8451: is the desired @samp{reconstruction}.@refill
        !          8452: 
        !          8453:   If you actually want the text of the abbrev in the buffer, rather than
        !          8454: its expansion, you can accomplish this by inserting the following
        !          8455: punctuation with @kbd{C-q}.  Thus, @kbd{foo C-q -} leaves @samp{foo-} in the
        !          8456: buffer.
        !          8457: 
        !          8458: @findex unexpand-abbrev
        !          8459:   If you expand an abbrev by mistake, you can undo the expansion (replace
        !          8460: the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}.
        !          8461: @kbd{C-_} (@code{undo}) can also be used to undo the expansion; but first
        !          8462: it will undo the insertion of the following punctuation character!
        !          8463: 
        !          8464: @findex expand-region-abbrevs
        !          8465:   @kbd{M-x expand-region-abbrevs} searches through the region for defined
        !          8466: abbrevs, and for each one found offers to replace it with its expansion.
        !          8467: This command is useful if you have typed in text using abbrevs but forgot
        !          8468: to turn on Abbrev mode first.  It may also be useful together with a
        !          8469: special set of abbrev definitions for making several global replacements at
        !          8470: once.
        !          8471: 
        !          8472: @node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs
        !          8473: @section Examining and Editing Abbrevs
        !          8474: 
        !          8475: @table @kbd
        !          8476: @item M-x list-abbrevs
        !          8477: Print a list of all abbrev definitions.
        !          8478: @item M-x edit-abbrevs
        !          8479: Edit a list of abbrevs; you can add, alter or remove definitions.
        !          8480: @end table
        !          8481: 
        !          8482: @findex list-abbrevs
        !          8483:   The output from @kbd{M-x list-abbrevs} looks like this:
        !          8484: 
        !          8485: @example
        !          8486: (lisp-mode-abbrev-table)
        !          8487: "dk"          0    "define-key"
        !          8488: (global-abbrev-table)
        !          8489: "dfn"         0    "definition"
        !          8490: @end example
        !          8491: 
        !          8492: @noindent
        !          8493: (Some blank lines of no semantic significance, and some other abbrev
        !          8494: tables, have been omitted.)
        !          8495: 
        !          8496:   A line containing a name in parentheses is the header for abbrevs in a
        !          8497: particular abbrev table; @code{global-abbrev-table} contains all the global
        !          8498: abbrevs, and the other abbrev tables that are named after major modes
        !          8499: contain the mode-specific abbrevs.
        !          8500: 
        !          8501:   Within each abbrev table, each nonblank line defines one abbrev.  The
        !          8502: word at the beginning is the abbrev.  The number that appears is the number
        !          8503: of times the abbrev has been expanded.  Emacs keeps track of this to help
        !          8504: you see which abbrevs you actually use, in case you decide to eliminate
        !          8505: those that you don't use often.  The string at the end of the line is the
        !          8506: expansion.
        !          8507: 
        !          8508: @findex edit-abbrevs
        !          8509: @kindex C-x C-s
        !          8510: @findex edit-abbrevs-redefine
        !          8511:   @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
        !          8512: definitions by editing a list of them in an Emacs buffer.  The list has the
        !          8513: same format described above.  The buffer of abbrevs is called @samp{*Abbrevs*},
        !          8514: and is in Edit-Abbrevs mode.  This mode redefines the key @kbd{C-x C-s} to
        !          8515: install the abbrev definitions as specified in the buffer.  The command
        !          8516: that does this is @code{edit-abbrevs-redefine}.  Any abbrevs not described
        !          8517: in the buffer are eliminated when this is done.
        !          8518: 
        !          8519:   @code{edit-abbrevs} is actually the same as @code{list-abbrevs} except
        !          8520: that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs}
        !          8521: merely displays it in another window.
        !          8522: 
        !          8523: @node Saving Abbrevs,, Editing Abbrevs, Abbrevs
        !          8524: @section Saving Abbrevs
        !          8525: 
        !          8526:   These commands allow you to keep abbrev definitions between editing
        !          8527: sessions.
        !          8528: 
        !          8529: @table @kbd
        !          8530: @item M-x write-abbrev-file
        !          8531: Write a file describing all defined abbrevs.
        !          8532: @item M-x read-abbrev-file
        !          8533: Read such a file and define abbrevs as specified there.
        !          8534: @item M-x quietly-read-abbrev-file
        !          8535: Similar but do not display a message about what is going on.
        !          8536: @item M-x define-abbrevs
        !          8537: Define abbrevs from buffer.
        !          8538: @item M-x insert-abbrevs
        !          8539: Insert all abbrevs and their expansions into the buffer.
        !          8540: @end table
        !          8541: 
        !          8542: @findex write-abbrev-file
        !          8543:   @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
        !          8544: writes a description of all current abbrev definitions into that file.  The
        !          8545: text stored in the file looks like the output of @kbd{M-x list-abbrevs}.
        !          8546: This is used to save abbrev definitions for use in a later session.
        !          8547: 
        !          8548: @findex read-abbrev-file
        !          8549: @findex quietly-read-abbrev-file
        !          8550: @vindex abbrev-file-name
        !          8551:   @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
        !          8552: reads the file, defining abbrevs according to the contents of the file.
        !          8553: @kbd{M-x quietly-read-abbrev-file} is the same except that it does not
        !          8554: display a message in the echo area saying that it is doing its work; it
        !          8555: is actually useful primarily in the @file{.emacs} file.  If an empty
        !          8556: argument is given to either of these functions, the file name used is the
        !          8557: value of the variable @code{abbrev-file-name}, which is by default
        !          8558: @code{"~/.abbrev_defs"}.
        !          8559: 
        !          8560: @vindex save-abbrevs
        !          8561:   Emacs will offer to save abbrevs automatically if you have changed any of
        !          8562: them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
        !          8563: C-c}).  This feature can be inhibited by setting the variable
        !          8564: @code{save-abbrevs} to @code{nil}.
        !          8565: 
        !          8566: @findex insert-abbrevs
        !          8567: @findex define-abbrevs
        !          8568:   The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
        !          8569: similar to the previous commands but work on text in an Emacs buffer.
        !          8570: @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
        !          8571: describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
        !          8572: the entire current buffer and defines abbrevs accordingly.@refill
        !          8573: 
        !          8574: @node Picture, Sending Mail, Abbrevs, Top
        !          8575: @chapter Editing Pictures
        !          8576: @cindex pictures
        !          8577: @findex edit-picture
        !          8578: 
        !          8579:   If you want to create a picture made out of text characters (for example,
        !          8580: a picture of the division of a register into fields, as a comment in a
        !          8581: program), use the command @code{edit-picture} to enter Picture mode.
        !          8582: 
        !          8583:   In Picture mode, editing is based on the @dfn{quarter-plane} model of
        !          8584: text, according to which the text characters lie studded on an area that
        !          8585: stretches infinitely far to the left and downward.  The concept of the end
        !          8586: of a line does not exist in this model; the most you can say is where the
        !          8587: last nonblank character on the line is found.
        !          8588: 
        !          8589:   Of course, Emacs really always considers text as a sequence of
        !          8590: characters, and lines really do have ends.  But in Picture mode most
        !          8591: frequently-used keys are rebound to commands that simulate the
        !          8592: quarter-plane model of text.  They do this by inserting spaces or by
        !          8593: converting tabs to spaces.
        !          8594: 
        !          8595:   Most of the basic editing commands of Emacs are redefined by Picture mode
        !          8596: to do essentially the same thing but in a quarter-plane way.  In addition,
        !          8597: Picture mode defines various keys starting with the @kbd{C-c} prefix to
        !          8598: run special picture editing commands.
        !          8599: 
        !          8600:   One of these keys, @kbd{C-c C-c}, is pretty important.  Often a picture
        !          8601: is part of a larger file that is usually edited in some other major mode.
        !          8602: @kbd{M-x edit-picture} records the name of the previous major mode, and
        !          8603: then you can use the @kbd{C-c C-c} command (@code{Picture-mode-exit}) to
        !          8604: restore that mode.  @kbd{C-c C-c} also deletes spaces from the ends of
        !          8605: lines, unless given a numeric argument.
        !          8606: 
        !          8607:   The commands used in Picture mode all work in other modes (provided the
        !          8608: @file{picture} library is loaded), but are not bound to keys except in
        !          8609: Picture mode.  Note that the descriptions below talk of moving ``one
        !          8610: column'' and so on, but all the picture mode commands handle numeric
        !          8611: arguments as their normal equivalents do.
        !          8612: 
        !          8613: @vindex picture-mode-hook
        !          8614:   Turning on Picture mode calls the value of the variable @code{picture-mode-hook}
        !          8615: as a function, with no arguments, if that value exists and is non-@code{nil}.
        !          8616: 
        !          8617: @menu
        !          8618: * Basic Picture::         Basic concepts and simple commands of Picture Mode.
        !          8619: * Insert in Picture::     Controlling direction of cursor motion
        !          8620:                            after "self-inserting" characters.
        !          8621: * Tabs in Picture::       Various features for tab stops and indentation.
        !          8622: * Rectangles in Picture:: Clearing and superimposing rectangles.
        !          8623: @end menu
        !          8624: 
        !          8625: @node Basic Picture, Insert in Picture, Picture Mode, Picture
        !          8626: @section Basic Editing in Picture Mode
        !          8627: 
        !          8628: @findex Picture-forward-column
        !          8629: @findex Picture-backward-column
        !          8630: @findex Picture-move-down
        !          8631: @findex Picture-move-up
        !          8632:   Most keys do the same thing in Picture mode that they usually do, but do
        !          8633: it in a quarter-plane style.  For example, @kbd{C-f} is rebound to run
        !          8634: @code{Picture-forward-column}, which is defined to move point one column to
        !          8635: the right, by inserting a space if necessary, so that the actual end of the
        !          8636: line makes no difference.  @kbd{C-b} is rebound to run
        !          8637: @code{Picture-backward-column}, which always moves point left one column,
        !          8638: converting a tab to multiple spaces if necessary.  @kbd{C-n} and @kbd{C-p}
        !          8639: are rebound to run @code{Picture-move-down} and @code{Picture-move-up},
        !          8640: which can either insert spaces or convert tabs as necessary to make sure
        !          8641: that point stays in exactly the same column.  @kbd{C-e} runs
        !          8642: @code{Picture-end-of-line}, which moves to after the last nonblank
        !          8643: character on the line.  There is no need to change @kbd{C-a}, as the choice
        !          8644: of screen model does not affect beginnings of lines.@refill
        !          8645: 
        !          8646: @findex Picture-newline
        !          8647:   Insertion of text is adapted to the quarter-plane screen model through
        !          8648: the use of Overwrite mode (@pxref{Minor Modes}).  Self-inserting characters
        !          8649: replace existing text, column by column, rather than pushing existing text
        !          8650: to the right.  @key{RET} runs @code{Picture-newline}, which just moves to
        !          8651: the beginning of the following line so that new text will replace that
        !          8652: line.
        !          8653: 
        !          8654: @findex Picture-backward-clear-column
        !          8655: @findex Picture-clear-column
        !          8656: @findex Picture-clear-line
        !          8657:   Deletion and killing of text are replaced with erasure.  @key{DEL}
        !          8658: (@code{Picture-backward-clear-column}) replaces the preceding character
        !          8659: with a space rather than removing it.  @kbd{C-d}
        !          8660: (@code{Picture-clear-column}) does the same thing in a forward direction.
        !          8661: @kbd{C-k} (@code{Picture-clear-line}) really kills the contents of lines,
        !          8662: but does not ever remove the newlines from the buffer.@refill
        !          8663: 
        !          8664: @findex Picture-open-line
        !          8665:   To do actual insertion, you must use special commands.  @kbd{C-o}
        !          8666: (@code{Picture-open-line}) still creates a blank line, but does so after
        !          8667: the current line; it never splits a line.  @kbd{C-M-o}, @code{split-line},
        !          8668: makes sense in Picture mode, so it is not changed.  @key{LFD}
        !          8669: (@code{Picture-duplicate-line}) inserts below the current line another line
        !          8670: with the same contents.@refill
        !          8671: 
        !          8672: @kindex C-c C-d
        !          8673: @findex delete-char
        !          8674:   Real deletion can be done with @kbd{C-w}, or with @kbd{C-c C-d} (which is
        !          8675: defined as @code{delete-char}, as @kbd{C-d} is in other modes), or with one
        !          8676: of the picture rectangle commands (@pxref{Rectangles in Picture}).
        !          8677: 
        !          8678: @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
        !          8679: @section Controlling Motion after Insert
        !          8680: 
        !          8681: @findex Picture-movement-up
        !          8682: @findex Picture-movement-down
        !          8683: @findex Picture-movement-left
        !          8684: @findex Picture-movement-right
        !          8685: @findex Picture-movement-nw
        !          8686: @findex Picture-movement-ne
        !          8687: @findex Picture-movement-sw
        !          8688: @findex Picture-movement-se
        !          8689: @kindex M-`
        !          8690: @kindex M-'
        !          8691: @kindex M--
        !          8692: @kindex M-=
        !          8693: @kindex C-c `
        !          8694: @kindex C-c '
        !          8695: @kindex C-c /
        !          8696: @kindex C-c \
        !          8697:   Since ``self-inserting'' characters in Picture mode just overwrite and
        !          8698: move point, there is no essential restriction on how point should be moved.
        !          8699: Normally point moves right, but you can specify any of the eight orthogonal
        !          8700: or diagonal directions for motion after a ``self-inserting'' character.
        !          8701: This is useful for drawing lines in the buffer.
        !          8702: 
        !          8703: @table @kbd
        !          8704: @item M-`
        !          8705: Move left after insertion (@code{Picture-movement-left}).
        !          8706: @item M-'
        !          8707: Move right after insertion (@code{Picture-movement-right}).
        !          8708: @item M--
        !          8709: Move up after insertion (@code{Picture-movement-up}).
        !          8710: @item M-=
        !          8711: Move down after insertion (@code{Picture-movement-down}).
        !          8712: @item C-c `
        !          8713: Move up and left (``northwest'') after insertion @*(@code{Picture-movement-nw}).
        !          8714: @item C-c '
        !          8715: Move up and right (``northeast'') after insertion @*
        !          8716: (@code{Picture-movement-ne}).
        !          8717: @item C-c /
        !          8718: Move down and left (``southwest'') after insertion
        !          8719: @*(@code{Picture-movement-sw}).
        !          8720: @item C-c \
        !          8721: Move down and right (``southeast'') after insertion
        !          8722: @*(@code{Picture-movement-se}).
        !          8723: @end table
        !          8724: 
        !          8725: @kindex C-c C-f
        !          8726: @kindex C-c C-b
        !          8727: @findex Picture-motion
        !          8728: @findex Picture-motion-reverse
        !          8729:   Two motion commands move based on the current Picture insertion
        !          8730: direction.  @kbd{C-c C-f} (@code{Picture-motion}) moves in the same
        !          8731: direction as motion after ``insertion'' currently does, while @kbd{C-c C-b}
        !          8732: (@code{Picture-motion-reverse}) moves in the opposite direction.
        !          8733: 
        !          8734: @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
        !          8735: @section Picture Mode Tabs
        !          8736: 
        !          8737: @kindex M-TAB
        !          8738: @findex Picture-tab-search
        !          8739: @vindex picture-tab-chars
        !          8740:   Two kinds of tab-like action are provided in Picture mode.
        !          8741: Context-based tabbing is done with @kbd{M-@key{TAB}}
        !          8742: (@code{Picture-tab-search}).  With no argument, it moves to a point
        !          8743: underneath the next ``interesting'' character that follows whitespace in
        !          8744: the previous nonblank line.  ``Next'' here means ``appearing at a
        !          8745: horizontal position greater than the one point starts out at''.  With an
        !          8746: argument, as in @kbd{C-u M-@key{TAB}}, this command moves to the next such
        !          8747: interesting character in the current line.  @kbd{M-@key{TAB}} does not
        !          8748: change the text; it only moves point.  ``Interesting'' characters are
        !          8749: defined by the variable @code{picture-tab-chars}, which contains a string
        !          8750: whose characters are all considered interesting.  Its default value is
        !          8751: @code{"!-~"}.@refill
        !          8752: 
        !          8753: @findex Picture-tab
        !          8754:   @key{TAB} itself runs @code{Picture-tab}, which operates based on the
        !          8755: current tab stop settings; it is the Picture mode equivalent of
        !          8756: @code{tab-to-tab-stop}.  Normally it just moves point, but with a numeric
        !          8757: argument it clears the text that it moves over.
        !          8758: 
        !          8759: @kindex C-c TAB
        !          8760: @findex Picture-set-tab-stops
        !          8761:   The context-based and tab-stop-based forms of tabbing are brought
        !          8762: together by the command @kbd{C-c @key{TAB}}, @code{Picture-set-tab-stops}.
        !          8763: This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
        !          8764: would consider significant in the current line.  The use of this command,
        !          8765: together with @key{TAB}, can get the effect of context-based tabbing.  But
        !          8766: @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
        !          8767: 
        !          8768: @node Rectangles in Picture,, Tabs in Picture, Picture
        !          8769: @section Picture Mode Rectangle Commands
        !          8770: @cindex rectangle
        !          8771: 
        !          8772:   Picture mode defines commands for working on rectangular pieces of the
        !          8773: text in ways that fit with the quarter-plane model.  The standard rectangle
        !          8774: commands may also be useful (@pxref{Rectangles}).
        !          8775: 
        !          8776: @table @kbd
        !          8777: @item C-c C-k
        !          8778: Clear out the region-rectangle (@code{Picture-clear-rectangle}).  With
        !          8779: argument, kill it.
        !          8780: @item C-c C-w @var{r}
        !          8781: Similar but save rectangle contents in register @var{r} first
        !          8782: (@code{Picture-clear-rectangle-to--register}).
        !          8783: @item C-c C-y
        !          8784: Overwrite last killed rectangle into the buffer, with upper left corner at
        !          8785: point (@code{Picture-yank-rectangle}).  With argument, insert instead.
        !          8786: @item C-c C-x @var{r}
        !          8787: Similar, but take the rectangle from register @var{r}
        !          8788: (@code{Picture-yank-rectangle-from-register}).
        !          8789: @end table
        !          8790: 
        !          8791: @kindex C-c C-k
        !          8792: @kindex C-c C-w
        !          8793: @findex Picture-clear-rectangle
        !          8794: @findex Picture-clear-rectangle-to-register
        !          8795:   The picture rectangle commands @kbd{C-c C-k}
        !          8796: (@code{Picture-clear-rectangle}) and @kbd{C-c C-w}
        !          8797: (@code{Picture-clear-rectangle-to-register}) differ from the standard
        !          8798: rectangle commands in that they normally clear the rectangle instead of
        !          8799: deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
        !          8800: mode.@refill
        !          8801: 
        !          8802:   However, deletion of rectangles can be useful in Picture mode, so these
        !          8803: commands delete the rectangle if given a numeric argument.
        !          8804: 
        !          8805: @kindex C-c C-y
        !          8806: @kindex C-c C-x
        !          8807: @findex Picture-yank-rectangle
        !          8808: @findex Picture-yank-rectangle-from-register
        !          8809:   The Picture mode commands for yanking rectangles differ from the standard
        !          8810: ones in overwriting instead of inserting.  This is the same way that
        !          8811: Picture mode insertion of other text is different from other modes.
        !          8812: @kbd{C-c C-y} (@code{Picture-yank-rectangle}) inserts (by overwriting) the
        !          8813: rectangle that was most recently killed, while @kbd{C-c C-x}
        !          8814: (@code{Picture-yank-rectangle-from-register}) does likewise for the
        !          8815: rectangle found in a specified register.
        !          8816: 
        !          8817: @node Sending Mail, Rmail, Picture, Top
        !          8818: @chapter Sending Mail
        !          8819: @cindex mail
        !          8820: @cindex message
        !          8821: 
        !          8822:   To send a message in Emacs, you start by typing a command (@kbd{C-x m})
        !          8823: to select and initialize the @samp{*mail*} buffer.  Then you edit the text
        !          8824: and headers of the message in this buffer, and type another command
        !          8825: (@kbd{C-c C-c}) to send the message.
        !          8826: 
        !          8827: @table @kbd
        !          8828: @item C-x m
        !          8829: Begin composing a message to send (@code{mail}).
        !          8830: @item C-x 4 m
        !          8831: Likewise, but display the message in another window
        !          8832: (@code{mail-other-window}).
        !          8833: @end table
        !          8834: 
        !          8835: @kindex C-x m
        !          8836: @findex mail
        !          8837: @kindex C-x 4 m
        !          8838: @findex mail-other-window
        !          8839:   The command @kbd{C-x m} (@code{mail}) selects a buffer named
        !          8840: @samp{*mail*} and initializes it with the skeleton of an outgoing message.
        !          8841: @kbd{C-x 4 m} (@code{mail-other-window}) selects the @samp{*mail*} buffer
        !          8842: in a different window, leaving the previous current buffer visible.@refill
        !          8843: 
        !          8844: @cindex headers (of message)
        !          8845:   In addition to the @dfn{text} or contents, a message has @dfn{header
        !          8846: fields} which say who sent it, when, to whom, why, and so on.  Some header
        !          8847: fields such as the date and sender are created automatically after the
        !          8848: message is sent.  Others, such as the recipient names, must be specified by
        !          8849: you in order to send the message properly.
        !          8850: 
        !          8851:   The line in the buffer that says
        !          8852: 
        !          8853: @example
        !          8854: --text follows this line--
        !          8855: @end example
        !          8856: 
        !          8857: @vindex mail-header-separator
        !          8858: @noindent
        !          8859: is a special delimiter that separates the headers you have specified from
        !          8860: the text.  Whatever follows this line is the text of the message; the
        !          8861: headers precede it.  The delimiter line itself does not appear in the
        !          8862: message actually sent.  The text used for the delimiter line is controlled
        !          8863: by the variable @code{mail-header-separator}.
        !          8864: 
        !          8865: Here is an example of what the headers and text in the @samp{*mail*} buffer
        !          8866: might look like.
        !          8867: 
        !          8868: @example
        !          8869: To: rms@@mc
        !          8870: CC: mly@@mc, rg@@oz
        !          8871: Subject: The Emacs Manual
        !          8872: --Text follows this line--
        !          8873: Please ignore this message.
        !          8874: @end example
        !          8875: 
        !          8876:   Because the mail composition buffer is an ordinary Emacs buffer, you can
        !          8877: switch to other buffers while in the middle of composing mail, and switch
        !          8878: back later (or never).  If you use the @kbd{C-x m} command again when you
        !          8879: have been composing another message but have not sent it, you are asked to
        !          8880: confirm before the old message is erased.  If you answer @kbd{n}, the
        !          8881: @samp{*mail*} buffer is left selected with its old contents, so you can
        !          8882: finish the old message and send it.  @kbd{C-u C-x m} is another way to do
        !          8883: this.  Sending the message marks the @samp{*mail*} buffer ``unmodified'',
        !          8884: which avoids the need for confirmation when @kbd{C-x m} is next used.
        !          8885: 
        !          8886: @section Mail Header Fields
        !          8887: 
        !          8888:   There are several header fields you can use in the @samp{*mail*} buffer.
        !          8889: Each header field starts with a field name at the beginning of a line,
        !          8890: terminated by a colon.  It does not matter whether you use upper or lower
        !          8891: case in the field name.  After the colon and optional whitespace comes the
        !          8892: contents of the field.
        !          8893: 
        !          8894: @table @samp
        !          8895: @item To
        !          8896: This field contains the mailing addresses to which the message is
        !          8897: addressed.
        !          8898: 
        !          8899: @item Subject
        !          8900: The contents of the @samp{Subject} field should be a piece of text
        !          8901: that says what the message is about.  The reason @samp{Subject} fields
        !          8902: are useful is that most mail-reading programs can provide a summary of
        !          8903: messages, listing the subject of each message but not its text.
        !          8904: 
        !          8905: @item CC
        !          8906: This field contains additional mailing addresses to send the message
        !          8907: to, but whose readers should not regard the message as addressed to
        !          8908: them.
        !          8909: 
        !          8910: @item BCC
        !          8911: This field contains additional mailing addresses to send the message
        !          8912: to, but which should not appear in the header of the message actually
        !          8913: sent.
        !          8914: 
        !          8915: @item FCC
        !          8916: This field contains the name of one file (in Unix mail file format) to
        !          8917: which a copy of the message should be appended when the message is
        !          8918: sent.
        !          8919: 
        !          8920: @item From
        !          8921: Use the @samp{From} field to say who you are, when the account you are
        !          8922: using to send the mail is not your own.  The contents of the
        !          8923: @samp{From} field should be a valid mailing address, since replies
        !          8924: will normally go there.
        !          8925: 
        !          8926: @item Reply-To
        !          8927: Use the @samp{Reply-to} field to direct replies to a different
        !          8928: address, not your own.  There is no difference between @samp{From} and
        !          8929: @samp{Reply-to} in their effect on where replies go, but they convey a
        !          8930: different meaning to the human who reads the message.
        !          8931: 
        !          8932: @item In-Reply-To
        !          8933: This field contains a piece of text describing a message you are
        !          8934: replying to.  Some mail systems can use this information to correlate
        !          8935: related pieces of mail.  Normally this field is filled in by Rmail
        !          8936: when you are replying to a message in Rmail, and you never need to
        !          8937: think about it.
        !          8938: @end table
        !          8939: 
        !          8940: @noindent
        !          8941: The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} fields can appear
        !          8942: any number of times, to specify many places to send the message.
        !          8943: 
        !          8944: @noindent
        !          8945: The @samp{To}, @samp{CC}, and @samp{BCC} fields can have continuation
        !          8946: lines.  All the lines starting with whitespace, following the line on
        !          8947: which the field starts, are considered part of the field.  For
        !          8948: example,@refill
        !          8949: 
        !          8950: @group
        !          8951: @example
        !          8952: To: foo@@bar, this@@that,
        !          8953:   me@@here
        !          8954: @end example
        !          8955: @end group
        !          8956: 
        !          8957: @noindent
        !          8958: If you have a @file{~/.mailrc} file, Rmail will scan it for mail aliases
        !          8959: the first time you try to send mail in an Rmail session.  Aliases found
        !          8960: in the @samp{To}, @samp{CC}, and @samp{BCC} fields will be expanded where
        !          8961: appropriate.
        !          8962: 
        !          8963: @vindex mail-archive-file-name
        !          8964:   If the variable @code{mail-archive-file-name} is non-@code{nil}, it should be a
        !          8965: string, naming a file; every time you start to edit a message to sent,
        !          8966: an @samp{FCC} field will be put in for that file.  Unless you remove the
        !          8967: @samp{FCC} field, every message will be written into that file when it is
        !          8968: sent.
        !          8969: 
        !          8970: @section Mail Mode
        !          8971: 
        !          8972:   The major mode used in the @samp{*mail*} buffer is Mail mode, which is
        !          8973: much like Text mode except that various special commands are provided on
        !          8974: the @kbd{C-c} prefix.  These commands all have to do specifically with
        !          8975: editing or sending the message.
        !          8976: 
        !          8977: @table @kbd
        !          8978: @item C-c C-s
        !          8979: Send the message, and leave the @samp{*mail*} buffer selected
        !          8980: (@code{mail-send}).
        !          8981: @item C-c C-c
        !          8982: Send the message, and select some other buffer (@code{mail-send-and-exit}).
        !          8983: @item C-c t
        !          8984: Move to the @samp{To} header field, creating one if there is none
        !          8985: (@code{mail-to}).
        !          8986: @item C-c s
        !          8987: Move to the @samp{Subject} header field, creating one if there is
        !          8988: none (@code{mail-subject}).
        !          8989: @item C-c c
        !          8990: Move to the @samp{CC} header field, creating one if there is none
        !          8991: (@code{mail-cc}).
        !          8992: @item C-c w
        !          8993: Insert the file @file{~/.signature} at the end of the message text
        !          8994: (@code{mail-signature}).
        !          8995: @item C-c y
        !          8996: Yank the selected message from Rmail (@code{mail-yank-original}).
        !          8997: This command does nothing unless your command to start sending a
        !          8998: message was issued with Rmail.
        !          8999: @item C-c q
        !          9000: Fill all paragraphs of yanked old messages, each individually
        !          9001: (@code{mail-fill-yanked-message}).
        !          9002: @end table
        !          9003: 
        !          9004: @kindex C-c C-s
        !          9005: @kindex C-c C-c
        !          9006: @findex mail-send
        !          9007: @findex mail-send-and-exit
        !          9008:   There are two ways to send the message.  @kbd{C-c C-s} (@code{mail-send})
        !          9009: sends the message and marks the @samp{*mail*} buffer unmodified, but leaves
        !          9010: that buffer selected so that you can modify the message (perhaps with new
        !          9011: recipients) and send it again.  @kbd{C-c C-c} (@code{mail-send-and-exit})
        !          9012: sends and then deletes the window (if there is another window) or switches
        !          9013: to another buffer.  It puts the @samp{*mail*} buffer at the lowest priority
        !          9014: for automatic reselection, since you are finished with using it.  This is
        !          9015: the usual way to send the message.
        !          9016: 
        !          9017: @kindex C-c t
        !          9018: @findex mail-to
        !          9019: @kindex C-c s
        !          9020: @findex mail-subject
        !          9021: @kindex C-c c
        !          9022: @findex mail-cc
        !          9023:   Mail mode provides some other special commands that are useful for
        !          9024: editing the headers and text of the message before you send it.  There are
        !          9025: four commands defined to move point to particular header fields: @kbd{C-c
        !          9026: t} (@code{mail-to}) to move to the @samp{To} field, @kbd{C-c s}
        !          9027: (@code{mail-subject}) for the @samp{Subject} field, and @kbd{C-c c}
        !          9028: (@code{mail-cc}) for the @samp{CC} field.@refill
        !          9029: 
        !          9030: @kindex C-c w
        !          9031: @findex mail-signature
        !          9032:   @kbd{C-c w} (@code{mail-signature}) adds a standard piece text at the end of the
        !          9033: message to say more about who you are.  The text comes from the file
        !          9034: @file{.signature} in your home directory.
        !          9035: 
        !          9036: @kindex C-c y
        !          9037: @findex mail-yank-original
        !          9038:   When mail sending is invoked from the Rmail mail reader using an Rmail
        !          9039: command, @kbd{C-c y} can be used inside the @samp{*mail*} buffer to insert
        !          9040: the text of the message you are replying to.  Normally it indents each line
        !          9041: of that message four spaces and eliminates most header fields.  A numeric
        !          9042: argument specifies the number of spaces to indent.  An argument of just
        !          9043: @kbd{C-u} says not to indent at all and not to eliminate anything.
        !          9044: @kbd{C-c y} always uses the current message from the @samp{rmail} buffer,
        !          9045: so you can insert several old messages by selecting one in @samp{rmail},
        !          9046: switching to @samp{*mail*} and yanking it, then switching back to
        !          9047: @samp{rmail} to select another.@refill
        !          9048: 
        !          9049: @kindex C-c q
        !          9050: @findex mail-fill-yanked-message
        !          9051:   After using @kbd{C-c y}, the command @kbd{C-c q} (@code{mail-fill-yanked-message}) can
        !          9052: be used to fill the paragraphs of the yanked old message or messages.  One
        !          9053: use of @kbd{C-c q} fills all such paragraphs, each one separately.
        !          9054: 
        !          9055: @vindex mail-mode-hook
        !          9056:   Turning on Mail mode (which @kbd{C-x m} does automatically) calls the
        !          9057: value of @code{text-mode-hook}, if it is not void or @code{nil}, and then calls
        !          9058: the value of @code{mail-mode-hook} if that is not void or @code{nil}.
        !          9059: 
        !          9060: @node Rmail, Recursive Edit, Sending Mail, Top
        !          9061: @chapter Reading Mail with Rmail
        !          9062: @cindex Rmail
        !          9063: @cindex message
        !          9064: 
        !          9065:   Rmail is an Emacs subsystem for reading and disposing of mail that you
        !          9066: receive.  Rmail stores mail messages in files called Rmail files.  Reading
        !          9067: the message in an Rmail file is done in a special major mode, Rmail mode,
        !          9068: which redefines most letters to run commands for managing mail.
        !          9069: 
        !          9070: @cindex primary mail file
        !          9071:   Using Rmail in the simplest fashion, you have one Rmail file @file{~/RMAIL}
        !          9072: in which all of your mail is saved.  It is called your @dfn{primary mail
        !          9073: file}.  In more sophisticated usage, you can copy messages into other Rmail
        !          9074: files and then edit those files with Rmail.
        !          9075: 
        !          9076:   Rmail displays only one message at a time.  It is called the @dfn{current
        !          9077: message}.  Rmail mode's special commands can do such things as move to
        !          9078: another message, delete the message, copy the message into another file, or
        !          9079: send a reply.
        !          9080: 
        !          9081: @cindex message number
        !          9082:   Within the Rmail file, messages are arranged sequentially in order
        !          9083: of receipt.  They are also assigned consecutive integers as their
        !          9084: @dfn{message numbers}.  The number of the current message is displayed
        !          9085: in Rmail's mode line, followed by the total number of messages in the
        !          9086: file.  You can move to a message by specifying its message number
        !          9087: using the @kbd{j} key (@pxref{Rmail Motion}).
        !          9088: 
        !          9089: @kindex s (Rmail)
        !          9090: @findex rmail-save
        !          9091:   Following the usual conventions of Emacs, changes in an Rmail file become
        !          9092: permanent only when the file is saved.  You can do this with @kbd{s}
        !          9093: (@code{rmail-save}), which also expunges deleted messages from the file
        !          9094: first (@pxref{Rmail Deletion}).  To save the file without expunging, use
        !          9095: @kbd{C-x C-s}.  Rmail saves the Rmail file spontaneously when moving new
        !          9096: mail from an inbox file (@pxref{Rmail Inbox}).
        !          9097: 
        !          9098: @kindex q (Rmail)
        !          9099: @findex rmail-quit
        !          9100:   You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and saves the
        !          9101: Rmail file and then switches to another buffer.  But there is no need to
        !          9102: `exit' formally.  If you switch from Rmail to editing in other buffers, and
        !          9103: never happen to switch back, you have exited.  Just make sure to save the
        !          9104: Rmail file eventually (like any other file you have changed).  @kbd{C-x s}
        !          9105: is a good enough way to do this (@pxref{Saving}).
        !          9106: 
        !          9107: @menu
        !          9108: * Scroll: Rmail Scrolling.   Scrolling through a message.
        !          9109: * Motion: Rmail Motion.      Moving to another message.
        !          9110: * Deletion: Rmail Deletion.  Deleting and expunging messages.
        !          9111: * Inbox: Rmail Inbox.        How mail gets into the Rmail file.
        !          9112: * Files: Rmail Files.        Using multiple Rmail files.
        !          9113: * Labels: Rmail Labels.      Classifying messages by labeling them.
        !          9114: * Summary: Rmail Summary.    Summaries show brief info on many messages.
        !          9115: * Reply: Rmail Reply.        Sending replies to messages you are viewing.
        !          9116: * Editing: Rmail Editing.    Editing message text and headers in Rmail.
        !          9117: * Digest: Rmail Digest.      Extracting the messages from a digest message.
        !          9118: @end menu
        !          9119: 
        !          9120: @node Rmail Scrolling, Rmail Motion, Rmail, Rmail
        !          9121: @section Scrolling Within a Message
        !          9122: 
        !          9123:   When Rmail displays a message that does not fit on the screen, it is
        !          9124: necessary to scroll through it.  This could be done with @kbd{C-v}, @kbd{M-v}
        !          9125: and @kbd{M-<}, but in Rmail scrolling is so frequent that it deserves to be
        !          9126: easier to type.
        !          9127: 
        !          9128: @table @kbd
        !          9129: @item @key{SPC}
        !          9130: Scroll forward (@code{scroll-up}).
        !          9131: @item @key{DEL}
        !          9132: Scroll backward (@code{scroll-down}).
        !          9133: @item .
        !          9134: Scroll to start of message (@code{rmail-beginning-of-message}).
        !          9135: @end table
        !          9136: 
        !          9137: @kindex SPC (Rmail)
        !          9138: @kindex DEL (Rmail)
        !          9139:   Since the most common thing to do while reading a message is to scroll
        !          9140: through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
        !          9141: @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down})
        !          9142: 
        !          9143: @kindex . (Rmail)
        !          9144: @findex rmail-beginning-of-message
        !          9145:   The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
        !          9146: beginning of the selected message.  This is not quite the same as @kbd{M-<}:
        !          9147: for one thing, it does not set the mark; for another, it resets the buffer
        !          9148: boundaries to the current message if you have changed them.
        !          9149: 
        !          9150: @node Rmail Motion, Rmail Deletion, Rmail Scrolling, Rmail
        !          9151: @section Moving Among Messages
        !          9152: 
        !          9153:   The most basic thing to do with a message is to read it.  The way to do
        !          9154: this in Rmail is to make the message current.  You can make any message
        !          9155: current given its message number using the @kbd{j} command, but the usual
        !          9156: thing to do is to move sequentially through the file, since this is the
        !          9157: order of receipt of messages.  When you enter Rmail, you are positioned at
        !          9158: the first new message (new messages are those received since the previous
        !          9159: use of Rmail), or at the last message if there are no new messages this
        !          9160: time.  Move forward to see the other new messages; move backward to
        !          9161: reexamine old messages.
        !          9162: 
        !          9163: @table @kbd
        !          9164: @item n
        !          9165: Move to the next nondeleted message, skipping any intervening
        !          9166: deleted messages (@code{rmail-next-undeleted-message}).
        !          9167: @item p
        !          9168: Move to the previous nondeleted message @*
        !          9169: (@code{rmail-previous-undeleted-message}).
        !          9170: @item M-n
        !          9171: Move to the next message, including deleted messages
        !          9172: (@code{rmail-next-message}).
        !          9173: @item M-p
        !          9174: Move to the previous message, including deleted messages
        !          9175: (@code{rmail-previous-message}).
        !          9176: @item j
        !          9177: Move to the first message.  With argument @var{n}, move to
        !          9178: message number @var{n} (@code{rmail-show-message}).
        !          9179: @item >
        !          9180: Move to the last message (@code{rmail-last-message}).
        !          9181: 
        !          9182: @item M-s @var{regexp} @key{RET}
        !          9183: Move to the next message containing a match for @var{regexp}
        !          9184: (@code{rmail-search}).  If @var{regexp} is empty, the last regexp used is
        !          9185: used again.
        !          9186: 
        !          9187: @item - M-s @var{regexp} @key{RET}
        !          9188: Move to the previous message containing a match for @var{regexp}.
        !          9189: If @var{regexp} is empty, the last regexp used is used again.
        !          9190: @end table
        !          9191: 
        !          9192: @kindex n (Rmail)
        !          9193: @kindex p (Rmail)
        !          9194: @kindex M-n (Rmail)
        !          9195: @kindex M-p (Rmail)
        !          9196: @findex rmail-next-undeleted-message
        !          9197: @findex rmail-previous-undeleted-message
        !          9198: @findex rmail-next-message
        !          9199: @findex rmail-previous-message
        !          9200:   @kbd{n} and @kbd{p} are the usual way of moving among messages in Rmail.  They
        !          9201: move through the messages sequentially, but skipping over deleted messages,
        !          9202: which is usually what you want to do.  Their command definitions are named
        !          9203: @code{rmail-next-undeleted-message} and @code{rmail-previous-undeleted-message}.  If
        !          9204: you do not want to skip deleted messages---for example, if you want to move
        !          9205: to a message to undelete it---use the variants @kbd{M-n} and @kbd{M-p}
        !          9206: (@code{rmail-next-message} and @code{rmail-previous-message}).  A numeric
        !          9207: argument to any of these commands serves as a repeat count.@refill
        !          9208: 
        !          9209: @kindex M-s (Rmail)
        !          9210: @findex rmail-search
        !          9211:   The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of search.  The
        !          9212: usual incremental search command @kbd{C-s} works in Rmail, but it searches
        !          9213: only within the current message.  The purpose of @kbd{M-s} is to search for
        !          9214: another message.  It reads a regular expression (@pxref{Regexps})
        !          9215: nonincrementally, then searches starting at the beginning of the following
        !          9216: message for a match.  The message containing the match is selected.
        !          9217: 
        !          9218:   To search backward in the file for another message, give @kbd{M-s} a
        !          9219: negative argument.  In Rmail this can be done with @kbd{- M-s}.
        !          9220: 
        !          9221: @kindex j (Rmail)
        !          9222: @kindex > (Rmail)
        !          9223: @findex rmail-show-message
        !          9224: @findex rmail-last-message
        !          9225:   To move to a message specified by absolute message number, use @kbd{j}
        !          9226: (@code{rmail-show-message}) with the message number as argument.  With no
        !          9227: argument, @kbd{j} selects the first message.  @kbd{>} (@code{rmail-last-message}) selects
        !          9228: the last message.
        !          9229: 
        !          9230: @node Rmail Deletion, Rmail Inbox, Rmail Motion, Rmail
        !          9231: @section Deleting Messages
        !          9232: 
        !          9233: @cindex deletion (Rmail)
        !          9234:   When you no longer need to keep a message, you can @dfn{delete} it.  This
        !          9235: flags it as ignorable, and some Rmail commands will pretend it is no longer
        !          9236: present; but it still has its place in the Rmail file, and still has its
        !          9237: message number.
        !          9238: 
        !          9239: @cindex expunging (Rmail)
        !          9240:   @dfn{Expunging} the Rmail file actually removes the deleted messages.
        !          9241: The remaining messages are renumbered consecutively.  Expunging is the only
        !          9242: action that changes the message number of any message, except for
        !          9243: undigestifying (@pxref{Rmail Digest}).
        !          9244: 
        !          9245: @table @kbd
        !          9246: @item d
        !          9247: Delete the current message, and move to the next nondeleted message
        !          9248: (@code{rmail-delete-forward}).
        !          9249: @item C-d
        !          9250: Delete the current message, and move to the previous nondeleted
        !          9251: message (@code{rmail-delete-backward}).
        !          9252: @item u
        !          9253: Move back to a deleted message and undelete it
        !          9254: (@code{rmail-undelete-previous-message}).
        !          9255: @item e
        !          9256: Expunge the Rmail file (@code{rmail-expunge}).
        !          9257: @end table
        !          9258: 
        !          9259: @kindex d (Rmail)
        !          9260: @kindex C-d (Rmail)
        !          9261: @findex rmail-delete-forward
        !          9262: @findex rmail-delete-backward
        !          9263:   There are two Rmail commands for deleting messages.  Both delete the
        !          9264: current message and select another message.  @kbd{d} (@code{rmail-delete-forward})
        !          9265: moves to the following message, skipping messages already deleted, while
        !          9266: @kbd{C-d} (@code{rmail-delete-backward}) moves to the previous nondeleted message.
        !          9267: If there is no nondeleted message to move to in the specified direction,
        !          9268: the message that was just deleted remains current.
        !          9269: 
        !          9270: @cindex undeletion (Rmail)
        !          9271: @kindex e (Rmail)
        !          9272: @findex rmail-expunge
        !          9273:   To make all the deleted messages finally vanish from the Rmail file,
        !          9274: type @kbd{e} (@code{rmail-expunge}).  Until you do this, you can still @dfn{undelete}
        !          9275: the deleted messages.
        !          9276: 
        !          9277: @kindex u (Rmail)
        !          9278: @findex rmail-undelete-previous-message
        !          9279:   To undelete, type
        !          9280: @kbd{u} (@code{rmail-undelete-previous-message}), which is designed to cancel the
        !          9281: effect of a @kbd{d} command (usually).  It undeletes the current message
        !          9282: if the current message is deleted.  Otherwise it moves backward to previous
        !          9283: messages until a deleted message is found, and undeletes that message.
        !          9284: 
        !          9285:   You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves
        !          9286: back to and undeletes the message that the @kbd{d} deleted.  But this does
        !          9287: not work when the @kbd{d} skips a few already-deleted messages that follow
        !          9288: the message being deleted; then the @kbd{u} command will undelete the last
        !          9289: of the messages that were skipped.  There is no clean way to avoid this
        !          9290: problem.  However, by repeating the @kbd{u} command, you can eventually get
        !          9291: back to the message that you intended to undelete.@refill
        !          9292: 
        !          9293:   A deleted message has the @samp{deleted} attribute, and as a result
        !          9294: @samp{deleted} appears in the mode line when the current message is
        !          9295: deleted.  In fact, deleting or undeleting a message is nothing more than
        !          9296: adding or removing this attribute.  @xref{Rmail Labels}.
        !          9297: 
        !          9298: @node Rmail Inbox, Rmail Files, Rmail Deletion, Rmail
        !          9299: @section Rmail Files and Inboxes
        !          9300: @cindex inbox file
        !          9301: 
        !          9302:   Unix places incoming mail for you in a file that we call your @dfn{inbox}.
        !          9303: When you start up Rmail, it copies the new messages from your inbox into
        !          9304: your primary mail file, an Rmail file, which also contains other messages
        !          9305: saved from previous Rmail sessions.  It is in this file that you actually
        !          9306: read the mail with Rmail.  This operation is called @dfn{getting new mail}.
        !          9307: It can be repeated at any time using the @kbd{g} key in Rmail.
        !          9308: 
        !          9309:   There are two reason for having separate Rmail files and inboxes.
        !          9310: 
        !          9311: @enumerate
        !          9312: @item
        !          9313: The format in which Unix delivers the mail in the inbox is not
        !          9314: adequate for Rmail mail storage.  It has no way to record attributes
        !          9315: (such as @samp{deleted}) or user-specified labels; it has no way to record
        !          9316: old headers and reformatted headers; it has no way to record cached
        !          9317: summary line information.
        !          9318: 
        !          9319: @item
        !          9320: It is very cumbersome to access an inbox file without danger of losing
        !          9321: mail, because it is necessary to interlock with mail delivery.
        !          9322: Moreover, different Unix systems use different interlocking
        !          9323: techniques.  The strategy of moving mail out of the inbox once and for
        !          9324: all into a separate Rmail file avoids the need for interlocking in all
        !          9325: the rest of Rmail, since only Rmail operates on the Rmail file.
        !          9326: @end enumerate
        !          9327: 
        !          9328:   When getting new mail, Rmail first copies the new mail from the inbox
        !          9329: file to the Rmail file; then it saves the Rmail file; then it deletes the
        !          9330: inbox file.  This way, a system crash may cause duplication of mail between
        !          9331: the inbox and the Rmail file, but cannot lose mail.
        !          9332: 
        !          9333: @node Rmail Files, Rmail Labels, Rmail Inbox, Rmail
        !          9334: @section Multiple Mail Files
        !          9335: 
        !          9336:   Rmail operates by default on your @dfn{primary mail file}, which is named
        !          9337: @file{~/RMAIL} and receives your incoming mail from your system inbox file.
        !          9338: But you can also have other mail files and edit them with Rmail.  These
        !          9339: files can receive mail through their own inboxes, or you can move messages
        !          9340: into them by explicit command in Rmail.
        !          9341: 
        !          9342: @table @kbd
        !          9343: @item i @var{file} @key{RET}
        !          9344: Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
        !          9345: 
        !          9346: @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
        !          9347: Specify inbox file names of current Rmail file.
        !          9348: 
        !          9349: @item g
        !          9350: Merge new mail from current Rmail file's inboxes
        !          9351: (@code{rmail-get-new-mail}).
        !          9352: 
        !          9353: @item C-u g @var{file}
        !          9354: Merge new mail from inbox file @var{file}.
        !          9355: 
        !          9356: @item o @var{file} @key{RET}
        !          9357: Append a copy of the current message to the file @var{file},
        !          9358: writing it in Rmail file format (@code{rmail-output-to-rmail-file}).
        !          9359: 
        !          9360: @item C-o @var{file} @key{RET}
        !          9361: Append a copy of the current message to the file @var{file},
        !          9362: writing it in Unix mail file format (@code{rmail-output}).
        !          9363: @end table
        !          9364: 
        !          9365: @kindex i (Rmail)
        !          9366: @findex rmail-input
        !          9367:   To run Rmail on a file other than your primary mail file, you may use the
        !          9368: @kbd{i} (@code{rmail-input}) command in Rmail.  This visits the file, puts it in
        !          9369: Rmail mode, and then gets new mail from the file's inboxes if any.
        !          9370: 
        !          9371:   The file you read with @kbd{i} does not have to be in Rmail file format.
        !          9372: It could also be Unix mail format, or mmdf format; or it could be a mixture
        !          9373: of all three, as long as each message belongs to one of the three formats.
        !          9374: Rmail recognizes all three and converts all the messages to proper Rmail
        !          9375: format before showing you the file.
        !          9376: 
        !          9377: @findex set-rmail-inbox-list
        !          9378:   Each Rmail file can contain a list of inbox file names; you can specify
        !          9379: this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
        !          9380: @key{RET}}.  The argument can contain any number of file names, separated
        !          9381: by commas.  It can also be empty, which specifies that this file should
        !          9382: have no inboxes.@refill
        !          9383: 
        !          9384: @kindex g (Rmail)
        !          9385: @findex rmail-get-new-mail
        !          9386:   If an Rmail file has inboxes, new mail is merged in from the inboxes when
        !          9387: the Rmail file is brought into Rmail, and when the @kbd{g} (@code{rmail-get-new-mail})
        !          9388: command is used.  If the Rmail file specifies no inboxes, then no new mail
        !          9389: is merged in at these times.  A special exception is made for your primary
        !          9390: mail file, in using the standard system inbox for it if it does not specify
        !          9391: any.
        !          9392: 
        !          9393:   Inboxes usually contain messages in Unix mail format, but they can just
        !          9394: as well contain Rmail or mmdf format messages.  Each message that is not in
        !          9395: Rmail format is converted, just as when an Rmail file is read in.
        !          9396: 
        !          9397:   To merge mail from a file that is not the usual inbox, give the @kbd{g}
        !          9398: key a numeric argument, as in @kbd{C-u g}.  Then it reads a file name and
        !          9399: merges mail from that file.  The inbox file is not deleted or changed in
        !          9400: any way when @kbd{g} with an argument is used.  This is, therefore, a
        !          9401: general way of merging one file of messages into another.
        !          9402: 
        !          9403: @kindex o (Rmail)
        !          9404: @findex rmail-output-to-rmail-file
        !          9405: @kindex C-o (Rmail)
        !          9406: @findex rmail-output
        !          9407:   If an Rmail file has no inboxes, how does it get anything in it?  By
        !          9408: explicit @kbd{o} or @kbd{C-o} commands in Rmail, or the like in other mail
        !          9409: processors.
        !          9410: 
        !          9411:   The @kbd{C-o} (@code{rmail-output}) command in Rmail writes a copy of the current
        !          9412: message into a specified file, in Unix mail file format.  This is useful
        !          9413: for moving messages into files to be read by other mail processors that do
        !          9414: not understand Rmail format.  @kbd{o} (@code{rmail-output-to-rmail-file}) is
        !          9415: another command that writes the message into a file in Rmail format.  This
        !          9416: is the best command to use to move messages between Rmail files.
        !          9417: 
        !          9418:   If you use @kbd{C-o} to move a message into an Rmail file, nothing bad
        !          9419: happens.  It's true that the Rmail file will contain a message in Unix
        !          9420: format, which is not strictly valid for an Rmail file; but next time Rmail
        !          9421: reads the mail file in, it will recognize the Unix format message and
        !          9422: convert it to Rmail format.  However, using @kbd{o} preserves any labels
        !          9423: the message has (@pxref{Rmail Labels}).
        !          9424: 
        !          9425:   Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the
        !          9426: message the @samp{filed} attribute, so that @samp{filed} appears in the mode
        !          9427: line when such a message is current.
        !          9428: 
        !          9429: @node Rmail Labels, Rmail Summary, Rmail Files, Rmail
        !          9430: @section Labels
        !          9431: @cindex label (Rmail)
        !          9432: @cindex attribute (Rmail)
        !          9433: 
        !          9434:   Each message can have various @dfn{labels} assigned to it as a means of
        !          9435: classification.  A label has a name; different names mean different labels.
        !          9436: Any given label is either present or absent on a particular message.  A few
        !          9437: label names have standard meanings and are given to messages automatically
        !          9438: by Rmail when appropriate; these special labels are called @dfn{attributes}.
        !          9439: All other labels are assigned by the user.
        !          9440: 
        !          9441: @table @kbd
        !          9442: @item a @var{label} @key{RET}
        !          9443: Assign the label @var{label} to the current message (@code{rmail-add-label}).
        !          9444: @item k @var{label} @key{RET}
        !          9445: Remove the label @var{label} to the current message (@code{rmail-kill-label}).
        !          9446: @item C-M-n @var{labels} @key{RET}
        !          9447: Move to the next message that has one of the labels @var{labels}
        !          9448: (@code{rmail-next-labeled-message}).
        !          9449: @item C-M-p @var{labels} @key{RET}
        !          9450: Move to the previous message that has one of the labels @var{labels}
        !          9451: (@code{rmail-previous-labeled-message}).
        !          9452: @item C-M-l @var{labels} @key{RET}
        !          9453: Make a summary of all messages containing any of the labels @var{labels}
        !          9454: (@code{rmail-summary-by-labels}).
        !          9455: @end table
        !          9456: 
        !          9457: @noindent
        !          9458: Specifying an empty string for one these commands means to use the last
        !          9459: label specified for any of these commands.
        !          9460: 
        !          9461: @kindex a (Rmail)
        !          9462: @kindex k (rmail)
        !          9463: @findex rmail-add-label
        !          9464: @findex rmail-kill-label
        !          9465:   The @kbd{a} (@code{rmail-add-label}) and @kbd{k} (@code{rmail-kill-label}) commands allow
        !          9466: you to assign or remove any label on the current message.  If the @var{label}
        !          9467: argument is empty, it means to assign or remove the same label most
        !          9468: recently assigned or removed.
        !          9469: 
        !          9470:   Once you have given messages labels to classify them as you wish, there
        !          9471: are two ways to use the labels: in moving, and in summaries.
        !          9472: 
        !          9473: @kindex C-M-n (Rmail)
        !          9474: @kindex C-M-p (Rmail)
        !          9475: @findex rmail-next-labeled-message
        !          9476: @findex rmail-previous-labeled-message
        !          9477:   The command @kbd{C-M-n @var{label} @key{RET}}
        !          9478: (@code{rmail-next-labeled-message}) moves to the next message that has one
        !          9479: of the labels @var{labels}.  @var{labels} is one or more label names,
        !          9480: separated by commas.  @kbd{C-M-p} (@code{rmail-previous-labeled-message})
        !          9481: is similar, but moves backwards to previous messages.  A preceding numeric
        !          9482: argument to either one serves as a repeat count.@refill
        !          9483: 
        !          9484: @kindex C-M-l (Rmail)
        !          9485: @findex rmail-summary-by-labels
        !          9486:   The command @kbd{C-M-l @var{labels} @key{RET}}
        !          9487: (@code{rmail-summary-by-labels}) displays a summary containing only the
        !          9488: messages that have at least one of a specified set of messages.  The
        !          9489: argument @var{labels} is one or more label names, separated by commas.
        !          9490: @xref{Rmail Summary}, for information on how summaries are used.@refill
        !          9491: 
        !          9492:   If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or @kbd{C-M-l} is empty, it means
        !          9493: to use the last set of labels specified for any of these commands.
        !          9494: 
        !          9495:   Some labels such as @samp{deleted} and @samp{filed} have built-in meanings and
        !          9496: are assigned to or removed from messages automatically at appropriate
        !          9497: times; these labels are called @dfn{attributes}.  Here is a list of Rmail
        !          9498: attributes:
        !          9499: 
        !          9500: @table @samp
        !          9501: @item unseen
        !          9502: Means the message has never been current.  Assigned to messages when
        !          9503: they come from an inbox file, and removed when a message is made
        !          9504: current.
        !          9505: @item deleted
        !          9506: Means the message is deleted.  Assigned by deletion commands and
        !          9507: removed by undeletion commands (@pxref{Rmail Deletion}).
        !          9508: @item filed
        !          9509: Means the message has been copied to some other file.  Assigned by the
        !          9510: file output commands (@pxref{Rmail Files}).
        !          9511: @item answered
        !          9512: Means you have mailed an answer to the message.  Assigned by the @kbd{r}
        !          9513: command (@code{rmail-reply}).  @xref{Rmail Reply}.
        !          9514: @item forwarded
        !          9515: Means you have forwarded the message to other users.  Assigned by the
        !          9516: @kbd{f} command (@code{rmail-forward}).  @xref{Rmail Reply}.
        !          9517: @end table
        !          9518: 
        !          9519:   All other labels are assigned or removed only by the user, and it is up
        !          9520: to the user to decide what they mean.
        !          9521: 
        !          9522: @node Rmail Summary, Rmail Reply, Rmail Labels, Rmail
        !          9523: @section Summaries
        !          9524: @cindex summary (Rmail)
        !          9525: 
        !          9526:   A @dfn{summary} is a buffer containing one line per message that Rmail
        !          9527: can make and display to give you an overview of the mail in an Rmail file.
        !          9528: Each line shows the message number, the sender, the labels, and the
        !          9529: subject.  When the summary buffer is selected, various commands can be used
        !          9530: to select messages by moving in the summary buffer, or delete or undelete
        !          9531: messages.
        !          9532: 
        !          9533:   A summary buffer applies to a single Rmail file only; if you are
        !          9534: editing multiple Rmail files, they have separate summary buffers.  The
        !          9535: summary buffer name is made by appending @samp{-summary} to the Rmail buffer's
        !          9536: name.  Only one summary buffer will be displayed at a time unless you make
        !          9537: several windows and select the summary buffers by hand.
        !          9538: 
        !          9539: @subsection Making Summaries
        !          9540: 
        !          9541: @table @kbd
        !          9542: @item h
        !          9543: @itemx C-M-h
        !          9544: Summarize all messages (@code{rmail-summary}).
        !          9545: @item l @var{labels} @key{RET}
        !          9546: @itemx C-M-l @var{labels} @key{RET}
        !          9547: Summarize message that have one or more of the specified labels
        !          9548: (@code{rmail-summary-by-labels}).
        !          9549: @item C-M-r @var{rcpts} @key{RET}
        !          9550: Summarize messages that have one or more of the specified recipients
        !          9551: (@code{rmail-summary-by-recipients})
        !          9552: @end table
        !          9553: 
        !          9554: @kindex h
        !          9555: @findex rmail-summary
        !          9556:   The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
        !          9557: for the current Rmail file with a summary of all the messages in the file.
        !          9558: It then displays and selects the summary buffer in another window.
        !          9559: 
        !          9560: @kindex l
        !          9561: @kindex C-M-l
        !          9562: @findex rmail-summary-by-labels
        !          9563:   @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
        !          9564: a partial summary mentioning only the messages that have one or more of the
        !          9565: labels @var{labels}.  @var{labels} should contain label names separated by
        !          9566: commas.@refill
        !          9567: 
        !          9568: @kindex C-M-r
        !          9569: @findex rmail-summary-by-recipients
        !          9570:   @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
        !          9571: makes a partial summary mentioning only the messages that have one or more
        !          9572: of the recipients @var{rcpts}.  @var{rcpts} should contain mailing
        !          9573: addresses separated by commas.@refill
        !          9574: 
        !          9575:   Note that there is only one summary buffer for any Rmail file; making one
        !          9576: kind of summary discards any previously made summary.  Also, summary
        !          9577: buffers are not updated automatically when the Rmail buffer is changed.
        !          9578: 
        !          9579: @subsection Editing in Summaries
        !          9580: 
        !          9581:   Summary buffers are given the major mode Rmail Summary mode, which
        !          9582: provides the following special commands:
        !          9583: 
        !          9584: @table @kbd
        !          9585: @item j
        !          9586: Select the message described by the line that point is on
        !          9587: (@code{rmail-summary-goto-msg}).
        !          9588: @item C-n
        !          9589: Move to next line and select its message in Rmail
        !          9590: (@code{rmail-summary-next-all}).
        !          9591: @item C-p
        !          9592: Move to previous line and select its message
        !          9593: (@code{rmail-summary-previous-all}).
        !          9594: @item n
        !          9595: Move to next line, skipping lines saying `deleted', and select its
        !          9596: message (@code{rmail-summary-next-msg}).
        !          9597: @item p
        !          9598: Move to previous line, skipping lines saying `deleted', and select
        !          9599: its message (@code{rmail-summary-previous-msg}).
        !          9600: @item d
        !          9601: Delete the current line's message, then do like @kbd{n}
        !          9602: (@code{rmail-summary-delete-forward}).
        !          9603: @item u
        !          9604: Undelete and select this message or the previous deleted message in
        !          9605: the summary (@code{rmail-summary-undelete}).
        !          9606: @item @key{SPC}
        !          9607: Scroll the other window (presumably Rmail) forward
        !          9608: (@code{rmail-summary-scroll-msg-up}).
        !          9609: @item @key{DEL}
        !          9610: Scroll the other window backward (@code{rmail-summary-scroll-msg-down}).
        !          9611: @item x
        !          9612: Kill the summary window (@code{rmail-summary-exit}).
        !          9613: @item q
        !          9614: Exit Rmail (@code{rmail-summary-quit}).
        !          9615: @end table
        !          9616: 
        !          9617: @kindex C-n (Rmail summary)
        !          9618: @kindex C-p (Rmail summary)
        !          9619: @findex rmail-summary-next-all
        !          9620: @findex rmail-summary-previous-all
        !          9621:   The keys @kbd{C-n} and @kbd{C-p} are modified in Rmail Summary mode so that in
        !          9622: addition to moving point in the summary buffer they also cause the line's
        !          9623: message to become current in the associated Rmail buffer.  That buffer is
        !          9624: also made visible in another window if it is not already so.
        !          9625: 
        !          9626: @kindex n (Rmail summary)
        !          9627: @kindex p (Rmail summary)
        !          9628: @findex rmail-summary-next-msg
        !          9629: @findex rmail-summary-previous-msg
        !          9630:   @kbd{n} and @kbd{p} are similar to @kbd{C-n} and @kbd{C-p}, but skip
        !          9631: lines that say `message deleted'.  They are like the @kbd{n} and @kbd{p}
        !          9632: keys of Rmail itself.  Note, however, that in a partial summary these
        !          9633: commands move only among the message listed in the summary.@refill
        !          9634: 
        !          9635: @kindex j (Rmail summary)
        !          9636: @findex rmail-summary-goto-msg
        !          9637:   The other Emacs cursor motion commands are not changed in Rmail Summary
        !          9638: mode, so it is easy to get the point on a line whose message is not
        !          9639: selected in Rmail.  This can also happen if you switch to the Rmail window
        !          9640: and switch messages there.  To get the Rmail buffer back in sync with the
        !          9641: summary, use the @kbd{j} (@code{rmail-summary-goto-msg}) command, which selects
        !          9642: in Rmail the message of the current summary line.
        !          9643: 
        !          9644: @kindex d (Rmail summary)
        !          9645: @kindex u (Rmail summary)
        !          9646: @findex rmail-summary-delete-forward
        !          9647: @findex rmail-summary-undelete
        !          9648:   Deletion and undeletion can also be done from the summary buffer.  They
        !          9649: always work based on where point is located in the summary buffer, ignoring
        !          9650: which message is selected in Rmail.  @kbd{d} (@code{rmail-summary-delete-forward})
        !          9651: deletes the current line's message, then moves to the next line whose
        !          9652: message is not deleted and selects that message.  The inverse of this is
        !          9653: @kbd{u} (@code{rmail-summary-undelete}), which moves back (if necessary) to a line
        !          9654: whose message is deleted, undeletes that message, and selects it in Rmail.
        !          9655: 
        !          9656: @kindex SPC (Rmail summary)
        !          9657: @kindex DEL (Rmail summary)
        !          9658: @findex rmail-summary-scroll-down
        !          9659: @findex rmail-summary-scroll-up
        !          9660:   When moving through messages with the summary buffer, it is convenient to
        !          9661: be able to scroll the message while remaining in the summary window.
        !          9662: The commands @key{SPC} (@code{rmail-summary-scroll-up}) and @key{DEL}
        !          9663: (@code{rmail-summary-scroll-down}) do this.  They scroll the message just
        !          9664: as those same keys do when the Rmail buffer is selected.@refill
        !          9665: 
        !          9666: @kindex x (Rmail summary)
        !          9667: @findex rmail-summary-exit
        !          9668:   When you are finished using the summary, type @kbd{x} (@code{rmail-summary-exit})
        !          9669: to kill the summary buffer's window.
        !          9670: 
        !          9671: @kindex q (Rmail summary)
        !          9672: @findex rmail-summary-quit
        !          9673:   You can also exit Rmail while in the summary.  @kbd{q} (@code{rmail-summary-quit})
        !          9674: kills the summary window, then saves the Rmail file and switches to another
        !          9675: buffer.
        !          9676: 
        !          9677: @node Rmail Reply, Rmail Editing, Rmail Summary, Rmail
        !          9678: @section Sending Replies
        !          9679: 
        !          9680:   Rmail has several commands that use Mail mode to send outgoing mail.
        !          9681: @xref{Sending Mail}, for information on using Mail mode.  What are
        !          9682: documented here are the special commands of Rmail for entering Mail mode.
        !          9683: Note that the usual keys for sending mail, @kbd{C-x m} and @kbd{C-x 4 m},
        !          9684: are available in Rmail mode and work just as they usually do.@refill
        !          9685: 
        !          9686: @table @kbd
        !          9687: @item m
        !          9688: Send a message (@code{rmail-mail}).
        !          9689: @item c
        !          9690: Continue editing already started outgoing message @*(@code{rmail-continue}).
        !          9691: @item r
        !          9692: Send a reply to the current Rmail message (@code{rmail-reply}).
        !          9693: @item f
        !          9694: Forward current message to other users (@code{rmail-forward}).
        !          9695: @end table
        !          9696: 
        !          9697: @kindex r (Rmail)
        !          9698: @findex rmail-reply
        !          9699: @vindex rmail-dont-reply-to
        !          9700: @cindex reply to a message
        !          9701:   The most common reason to send a message while in Rmail is to reply to
        !          9702: the message you are reading.  To do this, type @kbd{r}
        !          9703: (@code{rmail-reply}).  This displays the @samp{*mail*} buffer in another
        !          9704: window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
        !          9705: @samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
        !          9706: message being replied to.  The @samp{To} field is given the sender of that
        !          9707: message, and the @samp{CC} gets all the recipients of that message (but
        !          9708: recipients that match elements of the list @code{rmail-dont-reply-to} are
        !          9709: omitted; by default, this list contains your own mailing address).@refill
        !          9710: 
        !          9711:   Once you have initialized the @samp{*mail*} buffer this way, sending the
        !          9712: mail goes as usual (@pxref{Sending Mail}).  You can edit the presupplied
        !          9713: header fields if they are not right for you.
        !          9714: 
        !          9715: @kindex C-c y
        !          9716: @findex mail-yank-original
        !          9717:   One additional Mail mode command is available when mailing is invoked
        !          9718: from Rmail: @kbd{C-c y} (@code{mail-yank-original}) inserts into the outgoing
        !          9719: message a copy of the current Rmail message; normally this is the message
        !          9720: you are replying to, but you can also switch to the Rmail buffer, select a
        !          9721: different message, switch back, and yank new current message.  Normally the
        !          9722: yanked message is indented four spaces and has most header fields deleted
        !          9723: from it; an argument to @kbd{C-c y} specifies the amount to indent, and
        !          9724: @kbd{C-u C-c y} does not indent at all and does not delete any header
        !          9725: fields.@refill
        !          9726: 
        !          9727: @kindex f (Rmail)
        !          9728: @findex rmail-forward
        !          9729: @cindex forward a message
        !          9730:   Another frequent reason to send mail in Rmail is to forward the current
        !          9731: message to other users.  @kbd{f} (@code{rmail-forward}) makes this easy by
        !          9732: preinitializing the @samp{*mail*} buffer with the current message as the
        !          9733: text, and a subject designating a forwarded message.  All you have to do is
        !          9734: fill in the recipients and send.@refill
        !          9735: 
        !          9736: @kindex m (Rmail)
        !          9737: @findex rmail-mail
        !          9738:   The @kbd{m} (@code{rmail-mail}) command is used to start editing an
        !          9739: outgoing message that is not a reply.  It leaves the header fields empty.
        !          9740: Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
        !          9741: accessible for @kbd{C-c y}, just as @kbd{r} does.  Thus, @kbd{m} can be
        !          9742: used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
        !          9743: can do.@refill
        !          9744: 
        !          9745: @kindex c (Rmail)
        !          9746: @findex rmail-continue
        !          9747:   The @kbd{c} (@code{rmail-continue}) command resumes editing the
        !          9748: @samp{*mail*} buffer, to finish editing an outgoing message you were
        !          9749: already composing, or to alter a message you have sent.@refill
        !          9750: 
        !          9751: @node Rmail Editing, Rmail Digest, Rmail Reply, Rmail
        !          9752: @section Editing Within a Message
        !          9753: 
        !          9754:   Rmail mode provides a few special commands for moving within and editing
        !          9755: the current message.  In addition, the usual Emacs commands are available
        !          9756: (except for a few, such as @kbd{C-r} and @kbd{C-M-h}, that are redefined by Rmail for
        !          9757: other purposes).  However, the Rmail buffer is normally read-only, and to
        !          9758: alter it you must use the Rmail command @kbd{C-r} described below.
        !          9759: 
        !          9760: @table @kbd
        !          9761: @item t
        !          9762: Toggle display of original headers (@code{rmail-toggle-headers}).
        !          9763: @item C-r
        !          9764: Edit current message (@code{rmail-edit-current-message}).
        !          9765: @end table
        !          9766: 
        !          9767: @kindex t (Rmail)
        !          9768: @findex rmail-toggle-header
        !          9769: @vindex rmail-ignored-headers
        !          9770:   Rmail reformats the header of each message before displaying it.
        !          9771: Normally this involves deleting most header fields, on the grounds that
        !          9772: they are not interesting.  The variable @code{rmail-ignored-headers} should
        !          9773: contain a regexp that matches the header fields to discard in this way.
        !          9774: The original headers are saved permanently, and to see what they look like,
        !          9775: use the @kbd{t} (@code{rmail-toggle-headers}) command.  This discards the reformatted
        !          9776: headers of the current message and displays it with the original headers.
        !          9777: Repeating @kbd{t} reformats the message again.  Selecting the message again
        !          9778: also reformats.
        !          9779: 
        !          9780: @kindex C-r (Rmail)
        !          9781: @findex rmail-edit-current-message
        !          9782:   The Rmail buffer is normally read only, and most of the characters you
        !          9783: would type to modify it (including most letters) are redefined as Rmail
        !          9784: commands.  This is usually not a problem since it is rare to want to change
        !          9785: the text of a message.  When you do want to do this, the way is to type
        !          9786: @kbd{C-r} (@code{rmail-edit-current-message}), which changes from Rmail mode into
        !          9787: Rmail Edit mode, another major mode which is nearly the same as Text mode.
        !          9788: The mode line illustrates this change.
        !          9789: 
        !          9790:   In Rmail Edit mode, letters insert themselves as usual and the Rmail
        !          9791: commands are not available.  When you are finished editing the message and
        !          9792: are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
        !          9793: Rmail mode.  Alternatively, you can return to Rmail mode but cancel all the
        !          9794: editing that you have done by typing @kbd{C-c C-]}.
        !          9795: 
        !          9796: @vindex rmail-edit-mode-hook
        !          9797:   Entering Rmail Edit mode calls with no arguments the value of the variable
        !          9798: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
        !          9799: does the same with the variable @code{rmail-edit-mode-hook}.
        !          9800: 
        !          9801: @node Rmail Digest,, Rmail Editing, Rmail
        !          9802: @section Digest Messages
        !          9803: @cindex digest message
        !          9804: @cindex undigestify
        !          9805: 
        !          9806:   A @dfn{digest message} is a message which exists to contain and carry
        !          9807: several other messages.  Digests are used on moderated mailing lists; all
        !          9808: the messages that arrive for the list during a period of time such as one
        !          9809: day are put inside a single digest which is then sent to the subscribers.
        !          9810: Transmitting the single digest uses much less computer time than
        !          9811: transmitting the individual messages even though the total size is the
        !          9812: same, because the per-message overhead in network mail transmission is
        !          9813: considerable.
        !          9814: 
        !          9815: @findex undigestify-rmail-message
        !          9816:   When you receive a digest message, the most convenient way to read it is
        !          9817: to @dfn{undigestify} it: to turn it back into many individual messages.
        !          9818: Then you can read and delete the individual messages as it suits you.
        !          9819: 
        !          9820:   To undigestify a message, select it and then type @kbd{M-x
        !          9821: undigestify-rmail-message}.  This copies each submessage as a separate
        !          9822: Rmail message and inserts them all following the digest.  The digest
        !          9823: message itself is flagged as deleted.
        !          9824: 
        !          9825: @iftex
        !          9826: @chapter Miscellaneous Commands
        !          9827: 
        !          9828:   This chapter contains several brief topics that do not fit anywhere else.
        !          9829: 
        !          9830: @end iftex
        !          9831: @node Recursive Edit, Narrowing, Rmail, Top
        !          9832: @section Recursive Editing Levels
        !          9833: @cindex recursive edit
        !          9834: 
        !          9835:   A @dfn{recursive edit} is a situation in which you are using Emacs
        !          9836: commands to perform arbitrary editing while in the middle of another Emacs
        !          9837: command.  For example, when you type @kbd{C-r} inside of a @code{query-replace},
        !          9838: you enter a recursive edit in which you can change the current buffer.  On
        !          9839: exiting from the recursive edit, you go back to the @code{query-replace}.
        !          9840: 
        !          9841: @kindex C-M-c
        !          9842: @findex exit-recursive-edit
        !          9843: @cindex exiting
        !          9844:   @dfn{Exiting} the recursive edit means returning to the unfinished
        !          9845: command, which continues execution.  For example, exiting the recursive
        !          9846: edit requested by @kbd{C-r} in @code{query-replace} causes query replacing
        !          9847: to resume.  Exiting is done with @kbd{C-M-c} (@code{exit-recursive-edit}).
        !          9848: 
        !          9849: @kindex C-]
        !          9850: @findex abort-recursive-edit
        !          9851:   You can also @dfn{abort} the recursive edit.  This is like exiting, but
        !          9852: also quits the unfinished command immediately.  Use the command @kbd{C-]}
        !          9853: (@code{abort-recursive-edit}) for this.  @xref{Quitting}.
        !          9854: 
        !          9855:   The mode line shows you when you are in a recursive edit, by displaying
        !          9856: square brackets around the parentheses that always surround the major and
        !          9857: minor mode names.  Every window's mode line shows this, in the same way,
        !          9858: since being in a recursive edit is true regardless of what buffer is
        !          9859: selected.
        !          9860: 
        !          9861: @findex top-level
        !          9862:   It is possible to be in recursive edits within recursive edits.  For
        !          9863: example, after typing @kbd{C-r} in a @code{query-replace}, you might type a
        !          9864: command that entered the debugger.  In such circumstances, two or more sets
        !          9865: of square brackets appear in the mode line.  Exiting the inner recursive
        !          9866: edit (such as, with the debugger @kbd{c} command) would resume the command
        !          9867: where it called the debugger.  After the end of this command, you would be
        !          9868: able to exit the first recursive edit.  Aborting also gets out of only one
        !          9869: level of recursive edit; it returns immediately to the command level of the
        !          9870: previous recursive edit.  So you could immediately abort that one too.
        !          9871: 
        !          9872:   Alternatively, the command @kbd{M-x top-level} aborts all levels of
        !          9873: recursive edits, returning immediately to the top level command reader.
        !          9874: 
        !          9875:   The text being edited inside the recursive edit need not be the same text
        !          9876: that you were editing at top level.  It depends on what the recursive edit
        !          9877: is for.  If the command that invokes the recursive edit selects a different
        !          9878: buffer first, that is the buffer you will edit recursively.  In any case,
        !          9879: you can switch buffers within the recursive edit in the normal manner (as
        !          9880: long as the buffer-switching keys have not been rebound).  You could
        !          9881: probably do all the rest of your editing inside the recursive edit,
        !          9882: visiting files and all.  But this could have surprising effects (such as
        !          9883: stack overflow) from time to time.  So remember to exit or abort the
        !          9884: recursive edit when you no longer need it.
        !          9885: 
        !          9886:   In general, GNU Emacs tries to avoid using recursive edits.  It is
        !          9887: usually preferable to allow the user to switch among the possible editing
        !          9888: modes in any order he likes.  With recursive edits, the only way to get to
        !          9889: another state is to go ``back'' to the state that the recursive edit was
        !          9890: invoked from.
        !          9891: 
        !          9892: @node Narrowing, Shell, Recursive Edit, Top
        !          9893: @section Narrowing
        !          9894: @cindex widening
        !          9895: @cindex restriction
        !          9896: @cindex narrowing
        !          9897: 
        !          9898:   @dfn{Narrowing} means focusing in on some portion of the buffer, making
        !          9899: the rest temporarily invisible and inaccessible.  Cancelling the narrowing,
        !          9900: and making the entire buffer once again visible, is called @dfn{widening}.
        !          9901: The amount of narrowing in effect in a buffer at any time is called the
        !          9902: buffer's @dfn{restriction}.
        !          9903: 
        !          9904: @c WideCommands
        !          9905: @table @kbd
        !          9906: @item C-x n
        !          9907: Narrow down to between point and mark (@code{narrow-to-region}).
        !          9908: @item C-x w
        !          9909: Widen to make the entire buffer visible again (@code{widen}).
        !          9910: @end table
        !          9911: 
        !          9912:   When you have narrowed down to a part of the buffer, that part appears to
        !          9913: be all there is.  You can't see the rest, you can't move into it (motion
        !          9914: commands won't go outside the visible part), you can't change it in any
        !          9915: way.  However, it is not gone, and if you save the file all the invisible
        !          9916: text will be saved.  In addition to sometimes making it easier to
        !          9917: concentrate on a single subroutine or paragraph by eliminating clutter,
        !          9918: narrowing can be used to restrict the range of operation of a replace
        !          9919: command or repeating keyboard macro.  The word @samp{Narrow} appears in the
        !          9920: mode line whenever narrowing is in effect.
        !          9921: 
        !          9922: @kindex C-x n
        !          9923: @findex narrow-to-region
        !          9924:   The primary narrowing command is @kbd{C-x n} (@code{narrow-to-region}).
        !          9925: It sets the current buffer's restrictions so that the text in the current
        !          9926: region remains visible but all text before the region or after the region
        !          9927: is invisible.  Point and mark do not change.
        !          9928: 
        !          9929:   Because narrowing can easily confuse users who do not understand it,
        !          9930: @code{narrow-to-region} is normally a disabled command.  Attempting to use
        !          9931: this command asks for confirmation and gives you the option of enabling it;
        !          9932: once you enable the command, confirmation will no longer be required for
        !          9933: it.  @xref{Disabling}.
        !          9934: 
        !          9935: @kindex C-x w
        !          9936: @findex widen
        !          9937:   The way to undo narrowing is to widen with @kbd{C-x w} (@code{widen}).
        !          9938: This makes all text in the buffer accessible again.
        !          9939: 
        !          9940:   You can get information on what part of the buffer you are narrowed down
        !          9941: to using the @code{C-x =} command.  @xref{Position Info}.
        !          9942: 
        !          9943: @node Shell, Hardcopy, Narrowing, Top
        !          9944: @section Running Shell Commands from Emacs
        !          9945: @cindex subshell
        !          9946: @cindex shell commands
        !          9947: 
        !          9948:   Emacs has commands for passing single command lines to inferior shell
        !          9949: processes; it can also run a shell interactively with input and output to
        !          9950: an Emacs buffer @samp{*shell*}.
        !          9951: 
        !          9952: @table @kbd
        !          9953: @item M-!
        !          9954: Run a specified shell command line and display the output
        !          9955: (@code{shell-command}).
        !          9956: @item M-|
        !          9957: Run a specified shell command line with region contents as input;
        !          9958: optionally replace the region with the output
        !          9959: (@code{shell-command-on-region}).
        !          9960: @item M-x shell
        !          9961: Run a subshell with input and output through an Emacs buffer.
        !          9962: You can then give commands interactively.
        !          9963: @end table
        !          9964: 
        !          9965: @subsection Single Shell Commands
        !          9966: 
        !          9967: @kindex M-!
        !          9968: @findex shell-command
        !          9969:   @kbd{M-!} (@code{shell-command}) reads a line of text using the
        !          9970: minibuffer and creates an inferior shell to execute the line as a command.
        !          9971: Standard input from the command comes from the null device.  If the shell
        !          9972: command produces any output, the output goes into an Emacs buffer named
        !          9973: @samp{*Shell Command Output*}, which is displayed in another window but not
        !          9974: selected.  A numeric argument, as in @kbd{M-1 M-!}, directs this command to
        !          9975: insert any output into the current buffer.  In that case, point is left
        !          9976: before the output and the mark is set after the output.
        !          9977: 
        !          9978: @kindex M-|
        !          9979: @findex shell-command-on-region
        !          9980:   @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but passes
        !          9981: the contents of the region as input to the shell command, instead of no
        !          9982: input.  If a numeric argument is used, meaning insert output in the current
        !          9983: buffer, then the old region is deleted first and the output replaces it as
        !          9984: the contents of the region.@refill
        !          9985: 
        !          9986: @vindex shell-file-name
        !          9987: @cindex environment
        !          9988:   Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
        !          9989: shell to use.  This variable is initialized based on your @code{SHELL}
        !          9990: environment variable when Emacs is started.  If the file name does not
        !          9991: specify a directory, the directories in the list @code{exec-path} are
        !          9992: searched; this list is initialized based on the environment variable
        !          9993: @code{PATH} when Emacs is started.  Your @file{.emacs} file can override
        !          9994: either or both of these default initializations.@refill
        !          9995: 
        !          9996:   With @kbd{M-!} and @kbd{M-|}, Emacs has to wait until the shell command
        !          9997: completes.  You can quit with @kbd{C-g}; that terminates the shell command.
        !          9998: 
        !          9999: @subsection Interactive Inferior Shell
        !          10000: 
        !          10001: @findex M-x shell
        !          10002:   To run a subshell interactively, putting its typescript in an Emacs
        !          10003: buffer, use @kbd{M-x shell}.  This creates (or reuses) a buffer named
        !          10004: @samp{*shell*} and runs a subshell with input coming from and output going
        !          10005: to that buffer.  That is to say, any ``terminal output'' from the subshell
        !          10006: will go into the buffer, advancing point, and any ``terminal input'' for
        !          10007: the subshell comes from text in the buffer.  To give input to the subshell,
        !          10008: go to the end of the buffer and type the input, terminated by @key{RET}.
        !          10009: 
        !          10010:   Emacs does not wait for the subshell to do anything.  You can switch
        !          10011: windows or buffers and edit them while the shell is waiting, or while it is
        !          10012: running a command.  Output from the subshell waits until Emacs has time to
        !          10013: process it; this happens whenever Emacs is waiting for keyboard input or
        !          10014: for time to elapse.
        !          10015: 
        !          10016: @vindex explicit-shell-file-name
        !          10017:   The file name used to load the subshell is the value of the variable
        !          10018: @code{explicit-shell-file-name}, if that is non-@code{nil}.  Otherwise, the
        !          10019: environment variable @code{ESHELL} is used, or the environment variable
        !          10020: @code{SHELL} if there is no @code{ESHELL}.  If no directory is specified,
        !          10021: the directories in the list @code{exec-path} are searched; see
        !          10022: above.@refill
        !          10023: 
        !          10024:   As soon as the subshell is started, it is sent as input the contents of
        !          10025: the file @file{~/.emacs_@var{shellname}}, if that file exists, where
        !          10026: @var{shellname} is the name of the file that the shell was loaded from.
        !          10027: For example, if you use @code{csh}, the file sent to it is
        !          10028: @file{~/.emacs_csh}.@refill
        !          10029: 
        !          10030: @cindex Shell mode
        !          10031:   The shell buffer uses Shell mode, which defines several special keys
        !          10032: attached to the @kbd{C-c} prefix.  They are chosen to resemble the usual
        !          10033: editing and job control characters present in shells that are not under
        !          10034: Emacs, except that you must type @kbd{C-c} first.  Here is a complete list
        !          10035: of the special key bindings of Shell mode:
        !          10036: 
        !          10037: @kindex RET
        !          10038: @kindex C-c C-d
        !          10039: @kindex C-c C-u
        !          10040: @kindex C-c C-w
        !          10041: @kindex C-c C-c
        !          10042: @kindex C-c C-z
        !          10043: @kindex C-c C-\
        !          10044: @kindex C-c C-o
        !          10045: @kindex C-c C-r
        !          10046: @kindex C-c C-y
        !          10047: @findex send-shell-input
        !          10048: @findex shell-send-eof
        !          10049: @findex interrupt-shell-subjob
        !          10050: @findex stop-shell-subjob
        !          10051: @findex quit-shell-subjob
        !          10052: @findex kill-output-from-shell
        !          10053: @findex show-output-from-shell
        !          10054: @findex copy-last-shell-input
        !          10055: @vindex shell-prompt-pattern
        !          10056: @table @kbd
        !          10057: @item @key{RET}
        !          10058: At end of buffer send line as input; otherwise, copy current line to end of
        !          10059: buffer and send it (@code{send-shell-input}).  When a line is copied, any
        !          10060: text at the beginning of the line that matches the variable
        !          10061: @code{shell-prompt-pattern} is left out; this variable's value should be a
        !          10062: regexp string that matches the prompts that you use in your subshell.
        !          10063: @item C-c C-d
        !          10064: Send end-of-file as input, probably causing the shell or its current
        !          10065: subjob to finish (@code{shell-send-eof}).
        !          10066: @item C-c C-u
        !          10067: Kill all text that has yet to be sent as input (@code{kill-shell-input}).
        !          10068: @item C-c C-w
        !          10069: Kill a word before point (@code{backward-kill-word}).
        !          10070: @item C-c C-c
        !          10071: Interrupt the shell or its current subjob if any
        !          10072: (@code{interrupt-shell-subjob}).
        !          10073: @item C-c C-z
        !          10074: Stop the shell or its current subjob if any (@code{stop-shell-subjob}).
        !          10075: @item C-c C-\
        !          10076: Send quit signal to the shell or its current subjob if any
        !          10077: (@code{quit-shell-subjob}).
        !          10078: @item C-c C-o
        !          10079: Delete last batch of output from shell (@code{kill-output-from-shell}).
        !          10080: @item C-c C-r
        !          10081: Scroll top of last batch of output to top of window
        !          10082: (@code{show-output-from-shell}).
        !          10083: @item C-c C-y
        !          10084: Copy the previous bunch of shell input, and insert it into the
        !          10085: buffer before point (@code{copy-last-shell-input}).  No final newline
        !          10086: is inserted, and the input copied is not resubmitted until you type
        !          10087: @key{RET}.
        !          10088: @end table
        !          10089: 
        !          10090: @vindex shell-pushd-regexp
        !          10091: @vindex shell-popd-regexp
        !          10092: @vindex shell-cd-regexp
        !          10093:   @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
        !          10094: shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
        !          10095: default directory the same as the shell's working directory.  These
        !          10096: commands are recognized syntactically by examining lines of input that are
        !          10097: sent.  If you use aliases for these commands, you can tell Emacs to
        !          10098: recognize them also.  For example, if the value of the variable
        !          10099: @code{shell-pushd-regexp} matches the beginning of a shell command line,
        !          10100: that line is regarded as a @code{pushd} command.  Change this variable when
        !          10101: you add aliases for @samp{pushd}.  Likewise, @code{shell-popd-regexp} and
        !          10102: @code{shell-cd-regexp} are used to recognize commands with the meaning of
        !          10103: @samp{popd} and @samp{cd}.  These commands are recognized only at the
        !          10104: beginning of a shell command line.@refill
        !          10105: 
        !          10106: @node Hardcopy, Dissociated Press, Shell, Top
        !          10107: @section Hardcopy Output
        !          10108: @cindex hardcopy
        !          10109: 
        !          10110: @table @kbd
        !          10111: @item M-x print-buffer
        !          10112: Print hardcopy of current buffer using Unix command @code{lpr -p}.
        !          10113: This makes page headings containing the file name and page number.
        !          10114: @item M-x lpr-buffer
        !          10115: Print hardcopy of current buffer using Unix command @code{lpr}.
        !          10116: This makes no page headings.
        !          10117: @item M-x print-region
        !          10118: Like @code{print-buffer} but prints only the current region.
        !          10119: @item M-x lpr-region
        !          10120: Like @code{lpr-buffer} but prints only the current region.
        !          10121: @end table
        !          10122: 
        !          10123: @findex print-buffer
        !          10124: @findex print-region
        !          10125: @findex lpr-buffer
        !          10126: @findex lpr-region
        !          10127: @vindex lpr-switches
        !          10128:   All the hardcopy commands pass extra switches to the @code{lpr} program
        !          10129: based on the value of the variable @code{lpr-switches}.  Its value should
        !          10130: be a list of strings, each string a switch starting with @samp{-}.
        !          10131: 
        !          10132: @node Dissociated Press, Amusements, Hardcopy, Top
        !          10133: @section Dissociated Press
        !          10134: 
        !          10135: @findex dissociated-press
        !          10136:   @kbd{M-x dissociated-press} is a command for scrambling a file of text
        !          10137: either word by word or character by character.  Starting from a buffer of
        !          10138: straight English, it produces extremely amusing output.  The input comes
        !          10139: from the current Emacs buffer.  Dissociated Press writes its output in a
        !          10140: buffer named @samp{*Dissociation*}, and redisplays that buffer after every
        !          10141: couple of lines (approximately) to facilitate reading it.
        !          10142: 
        !          10143:   @code{dissociated-press} asks every so often whether to continue
        !          10144: operating.  Answer @kbd{n} to stop it.  You can also stop at any time by
        !          10145: typing @kbd{C-g}.  The dissociation output remains in the @samp{*Dissociation*}
        !          10146: buffer for you to copy elsewhere if you wish.
        !          10147: 
        !          10148: @cindex presidentagon
        !          10149:   Dissociated Press operates by jumping at random from one point in the
        !          10150: buffer to another.  In order to produce plausible output rather than
        !          10151: gibberish, it insists on a certain amount of overlap between the end of one
        !          10152: run of consecutive words or characters and the start of the next.  That is,
        !          10153: if it has just printed out `president' and then decides to jump to a
        !          10154: different point in the file, it might spot the `ent' in `pentagon' and
        !          10155: continue from there, producing `presidentagon'.  Long sample texts produce
        !          10156: the best results.
        !          10157: 
        !          10158: @cindex againformation
        !          10159:   A positive argument to @kbd{M-x Dissociated Press} tells it to operate
        !          10160: character by character, and specifies the number of overlap characters.  A
        !          10161: negative argument tells it to operate word by word and specifies the number
        !          10162: of overlap words.  In this mode, whole words are treated as the elements to
        !          10163: be permuted, rather than characters.  No argument is equivalent to an
        !          10164: argument of two.  For your againformation, the output goes only into the
        !          10165: buffer @samp{*Dissociation*}.  The buffer you start with is not changed.
        !          10166: 
        !          10167: @cindex Markov chain
        !          10168: @cindex ignoriginal
        !          10169: @cindex techniquitous
        !          10170:   Dissociated Press produces nearly the same results as a Markov chain
        !          10171: based on a frequency table constructed from the sample text.  It is,
        !          10172: however, an independent, ignoriginal invention.  Dissociated Press
        !          10173: techniquitously copies several consecutive characters from the sample
        !          10174: between random choices, whereas a Markov chain would choose randomly for
        !          10175: each word or character.  This makes for more plausible sounding results,
        !          10176: and runs faster.
        !          10177: 
        !          10178: @cindex outragedy
        !          10179: @cindex buggestion
        !          10180: @cindex properbose
        !          10181:   It is a mustatement that too much use of Dissociated Press can be a
        !          10182: developediment to your real work.  Sometimes to the point of outragedy.
        !          10183: And keep dissociwords out of your documentation, if you want it to be well
        !          10184: userenced and properbose.  Have fun.  Your buggestions are welcome.
        !          10185: 
        !          10186: @node Amusements, Customization, Dissociated Press, Top
        !          10187: @section Other Amusements
        !          10188: @cindex boredom
        !          10189: @findex hanoi
        !          10190: 
        !          10191:   If you are a little bit bored, you can try @kbd{M-x hanoi}.  If you are
        !          10192: considerably bored, give it a numeric argument.  If you are very very
        !          10193: bored, try an argument of 9.
        !          10194: 
        !          10195:   When you are frustrated, try the famous Eliza program.  Just do
        !          10196: @kbd{M-x doctor}.
        !          10197: 
        !          10198: @node Customization, Quitting, Amusements, Top
        !          10199: @chapter Customization
        !          10200: @cindex customization
        !          10201: 
        !          10202:   This chapter talks about various topics relevant to adapting the
        !          10203: behavior of Emacs in minor ways.
        !          10204: 
        !          10205:   All kinds of customization affect only the particular Emacs job that you
        !          10206: do them in.  They are completely lost when you kill the Emacs job, and have
        !          10207: no effect on other Emacs jobs you may run at the same time or later.  The
        !          10208: only way an Emacs job can affect anything outside of it is by writing a
        !          10209: file; in particular, the only way to make a customization `permanent' is to
        !          10210: put something in your @file{.emacs} file or other appropriate file to do the
        !          10211: customization in each session.  @xref{Init File}.
        !          10212: 
        !          10213: @menu
        !          10214: * Minor Modes::     Each minor mode is one feature you can turn on
        !          10215:                      independently of any others.
        !          10216: * Variables::       Many Emacs commands examine Emacs variables
        !          10217:                      to decide what to do; by setting variables,
        !          10218:                      you can control their functioning.
        !          10219: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
        !          10220:                      to be replayed with a single command.
        !          10221: * Key Bindings::    The keymaps say what command each key runs.
        !          10222:                      By changing them, you can "redefine keys".
        !          10223: * Syntax::          The syntax table controls how words and expressions
        !          10224:                      are parsed.
        !          10225: * Init File::       How to write common customizations in the @file{.emacs} file.
        !          10226: @end menu
        !          10227: 
        !          10228: @node Minor Modes, Variables, Customization, Customization
        !          10229: @section Minor Modes
        !          10230: @cindex minor modes
        !          10231: 
        !          10232: @cindex mode line
        !          10233:   Minor modes are options which you can use or not.  For example, Auto Fill
        !          10234: mode is a minor mode in which @key{SPC} breaks lines between words as you
        !          10235: type.  All the minor modes are independent of each other and of the
        !          10236: selected major mode.  Most minor modes say in the mode line when they are
        !          10237: on; for example, @samp{Fill} in the mode line means that Auto Fill mode is
        !          10238: on.
        !          10239: 
        !          10240:   Append @code{-mode} to the name of a minor mode to get the name of a
        !          10241: command function that turns the mode on or off.  Thus, the command to
        !          10242: enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}.  These
        !          10243: commands are usually invoked with @kbd{M-x}, but you can bind keys to them
        !          10244: if you wish.  With no argument, the function turns the mode on if it was
        !          10245: off and off if it was on.  This is known as @dfn{toggling}.  A positive
        !          10246: argument always turns the mode on, and an explicit zero argument or a
        !          10247: negative argument always turns it off.
        !          10248: 
        !          10249: @cindex Auto Fill mode
        !          10250:   Auto Fill mode allows you to enter filled text without breaking lines
        !          10251: explicitly.  Emacs inserts newlines as necessary to prevent lines from
        !          10252: becoming too long.  @xref{Filling}.
        !          10253: 
        !          10254: @cindex Overwrite mode
        !          10255:   Overwrite mode causes ordinary printing characters to replace existing
        !          10256: text instead of shoving it over.  For example, if the point is in front of
        !          10257: the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a @kbd{G}
        !          10258: changes it to @samp{FOOGAR}, instead of making it @samp{FOOGBAR} as
        !          10259: usual.@refill
        !          10260: 
        !          10261: @cindex Abbrev mode
        !          10262:   Abbrev mode allows you to define abbreviations that automatically expand
        !          10263: as you type them.  For example, @samp{amd} might expand to @samp{abbrev
        !          10264: mode}.  @xref{Abbrevs}, for full information.
        !          10265: 
        !          10266: @node Variables, Keyboard Macros, Minor Modes, Customization
        !          10267: @section Variables
        !          10268: @cindex variable
        !          10269: @cindex option
        !          10270: 
        !          10271:   A @dfn{variable} is a Lisp symbol which has a value.  The symbol's name
        !          10272: is also called the name of the variable.  Variable names can contain any
        !          10273: characters, but conventionally they are chosen to be words separated by
        !          10274: hyphens.  A variable can have a documentation string which describes what
        !          10275: kind of value it should have and how the value will be used.
        !          10276: 
        !          10277:   Lisp allows any variable to have any kind of value, but most variables
        !          10278: that Emacs uses require a value of a certain type.  Often the value should
        !          10279: always be a string, or should always be a number.  Sometimes we say that a
        !          10280: certain feature is turned on if a variable is ``non-@code{nil},'' meaning
        !          10281: that if the variable's value is @code{nil}, the feature is off, but the
        !          10282: feature is on for @i{any} other value.  The conventional value to use to
        !          10283: turn on the feature---since you have to pick one particular value when you
        !          10284: set the variable---is @code{t}.
        !          10285: 
        !          10286:   Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
        !          10287: program must, but the most interesting variables for you are the ones that
        !          10288: exist for the sake of customization.  Emacs does not (usually) change the
        !          10289: values of these variables; instead, you set the values, and thereby alter
        !          10290: and control the behavior of certain Emacs commands.  These variables are
        !          10291: called @dfn{options}.  Most options are documented in this manual, and
        !          10292: appear in the Variable Index (@pxref{Variable Index}).
        !          10293: 
        !          10294:   One example of a variable which is an option is @code{fill-column}, which
        !          10295: specifies the position of the right margin (as a number of characters from
        !          10296: the left margin) to be used by the fill commands (@pxref{Filling}).
        !          10297: 
        !          10298: @menu
        !          10299: * Examining::           Examining or setting one variable's value.
        !          10300: * Edit Options::        Examining or editing list of all variables' values.
        !          10301: * Locals::              Per-buffer values of variables.
        !          10302: * File Variables::      How files can specify variable values.
        !          10303: @end menu
        !          10304: 
        !          10305: @node Examining, Edit Options, Variables, Variables
        !          10306: @subsection Examining and Setting Variables
        !          10307: 
        !          10308: @table @kbd
        !          10309: @item C-h v
        !          10310: @itemx M-x describe-variable
        !          10311: Print the value and documentation of a variable.
        !          10312: @item M-x set-variable
        !          10313: Change the value of a variable.
        !          10314: @end table
        !          10315: 
        !          10316: @kindex C-h v
        !          10317: @findex describe-variable
        !          10318:   To examine the value of a single variable, use @kbd{C-h v}
        !          10319: (@code{describe-variable}), which reads a variable name using the
        !          10320: minibuffer, with completion.  It prints both the value and the
        !          10321: documentation of the variable.
        !          10322: 
        !          10323: @example
        !          10324: C-h v fill-column @key{RET}
        !          10325: @end example
        !          10326: @noindent
        !          10327: prints something like
        !          10328: @smallexample
        !          10329: fill-column's value is 75
        !          10330: 
        !          10331: Documentation:
        !          10332: *Column beyond which automatic line-wrapping should happen.
        !          10333: Separate value in each buffer.
        !          10334: @end smallexample
        !          10335: 
        !          10336: @cindex option
        !          10337: @noindent
        !          10338: The star at the beginning of the documentation indicates that this variable
        !          10339: is an option.  @kbd{C-h v} is not restricted to options; they allow any
        !          10340: variable name.
        !          10341: 
        !          10342: @findex set-variable
        !          10343:   If you know which option you want to set, you can set it using @kbd{M-x
        !          10344: set-variable}.  This reads the variable name with the minibuffer (with
        !          10345: completion), and then reads a Lisp expression for the new value using the
        !          10346: minibuffer a second time.  For example,
        !          10347: 
        !          10348: @example
        !          10349: M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET}
        !          10350: @end example
        !          10351: 
        !          10352: @noindent
        !          10353: sets @code{fill-column} to 75.
        !          10354: 
        !          10355: @node Edit Options, Locals, Examining, Variables
        !          10356: @subsection Editing Variable Values
        !          10357: 
        !          10358: @table @kbd
        !          10359: @item M-x list-options
        !          10360: Display a buffer listing names, values and documentation of all options.
        !          10361: @item M-x edit-options
        !          10362: Change option values by editing a list of options.
        !          10363: @end table
        !          10364: 
        !          10365: @findex list-options
        !          10366:   @kbd{M-x list-options} displays a list of all Emacs option variables, in
        !          10367: an Emacs buffer named @samp{*List Options*}.  Each option is shown with its
        !          10368: documentation and its current value.  Here is what a portion of it might
        !          10369: look like:
        !          10370: 
        !          10371: @smallexample
        !          10372: ;; exec-path:
        !          10373:        ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
        !          10374: *List of directories to search programs to run in subprocesses.
        !          10375: Each element is a string (directory name) or nil (try default directory).
        !          10376: ;;
        !          10377: ;; fill-column:
        !          10378:        75
        !          10379: *Column beyond which automatic line-wrapping should happen.
        !          10380: Separate value in each buffer.
        !          10381: ;;
        !          10382: ;; find-file-hook:
        !          10383:        nil
        !          10384: *If non-nil specifies a function to be called after a buffer
        !          10385: is found or reverted from a file.
        !          10386: The buffer's local variables (if any) will have been processed
        !          10387: before the function is called.
        !          10388: ;;
        !          10389: @end smallexample
        !          10390: 
        !          10391: @findex edit-options
        !          10392:   @kbd{M-x edit-options} goes one step farther and selects the @samp{*List
        !          10393: Options*} buffer; this buffer uses the major mode Options mode, which
        !          10394: provides commands that allow you to point at an option and change its
        !          10395: value:
        !          10396: 
        !          10397: @table @kbd
        !          10398: @item s
        !          10399: Set the variable point is in or near to a new value read using the
        !          10400: minibuffer.
        !          10401: @item x
        !          10402: Toggle the variable point is in or near: if the value was @code{nil},
        !          10403: it becomes @code{t}; otherwise it becomes @code{nil}.
        !          10404: @item 1
        !          10405: Set the variable point is in or near to @code{t}.
        !          10406: @item 0
        !          10407: Set the variable point is in or near to @code{nil}.
        !          10408: @item n
        !          10409: @itemx p
        !          10410: Move to the next or previous variable.
        !          10411: @end table
        !          10412: 
        !          10413: @node Locals, File Variables, Edit Options, Variables
        !          10414: @subsection Local Variables
        !          10415: 
        !          10416: @table @kbd
        !          10417: @item M-x make-local-variable
        !          10418: Make a variable have a local value in the current buffer.
        !          10419: @item M-x kill-local-variable
        !          10420: Make a variable use its global value in the current buffer.
        !          10421: @end table
        !          10422: 
        !          10423: @cindex local variables
        !          10424:   Any variable can be made @dfn{local} to a specific Emacs buffer.  This
        !          10425: means that its value in that buffer is independent of its value in other
        !          10426: buffers.  A few variables are always local in every buffer.  Every other
        !          10427: Emacs variable has a @dfn{global} value which is in effect in all buffers
        !          10428: that have not made the variable local.
        !          10429: 
        !          10430:   Major modes always make the variables they set local to the buffer.
        !          10431: This is why changing major modes in one buffer has no effect on other
        !          10432: buffers.
        !          10433: 
        !          10434: @findex make-local-variable
        !          10435:   @kbd{M-x make-local-variable} reads the name of a variable and makes it
        !          10436: local to the current buffer.  Further changes in this buffer will not
        !          10437: affect others, and further changes in the global value will not affect this
        !          10438: buffer.
        !          10439: 
        !          10440: @findex kill-local-variable
        !          10441:   @kbd{M-x kill-local-variable} reads the name of a variable and makes it
        !          10442: cease to be local to the current buffer.  The global value of the variable
        !          10443: henceforth is in effect in this buffer.  Setting the major mode kills all
        !          10444: the local variables of the buffer, except for those variables that are
        !          10445: always local to every buffer.
        !          10446: 
        !          10447: @node File Variables,, Locals, Variables
        !          10448: @subsection Local Variables in Files
        !          10449: @cindex local variables in files
        !          10450: 
        !          10451:   A file can contain a @dfn{local variables list}, which specifies the
        !          10452: values to use for certain Emacs variables when that file is edited.
        !          10453: Visiting the file checks for a local variables list and makes each variable
        !          10454: in the list local to the buffer in which the file is visited, with the
        !          10455: value specified in the file.
        !          10456: 
        !          10457:   A local variables list goes near the end of the file, in the last page.
        !          10458: (It is often best to put it on a page by itself.)  The local variables list
        !          10459: starts with a line containing the string @samp{Local Variables:}, and ends
        !          10460: with a line containing the string @samp{End:}.  In between come the
        !          10461: variable names and values, one set per line, as @samp{@var{variable}:@:
        !          10462: @var{value}}.  The @var{value}s are not evaluated; they are used literally.
        !          10463: 
        !          10464:   The line which starts the local variables list does not have to say just
        !          10465: @samp{Local Variables:}.  If there is other text before @samp{Local
        !          10466: Variables:}, that text is called the @dfn{prefix}, and if there is other
        !          10467: text after, that is called the @dfn{suffix}.  If these are present, each
        !          10468: entry in the local variables list should have the prefix before it and the
        !          10469: suffix after it.  This includes the @samp{End:} line.  The prefix and
        !          10470: suffix are included to disguise the local variables list as a comment so
        !          10471: that the compiler or text formatter will not be perplexed by it.  If you do
        !          10472: not need to disguise the local variables list as a comment in this way, do
        !          10473: not bother with a prefix or a suffix.@refill
        !          10474: 
        !          10475:   Two ``variable'' names are special in a local variables list: a value for
        !          10476: the variable @code{mode} really sets the major mode, and a value for the
        !          10477: variable @code{eval} is simply evaluated as an expression and the value is
        !          10478: ignored.  These are not real variables; setting such variables in any other
        !          10479: context has no such effect.  If @code{mode} is used in a local variables
        !          10480: list, it should be the first entry in the list.
        !          10481: 
        !          10482: Here is an example of a local variables list:
        !          10483: @example
        !          10484: ;;; Local Variables: ***
        !          10485: ;;; mode:lisp ***
        !          10486: ;;; comment-column:0 ***
        !          10487: ;;; comment-start: ";;; "  ***
        !          10488: ;;; comment-end:"***" ***
        !          10489: ;;; End: ***
        !          10490: @end example
        !          10491: 
        !          10492:   Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}.  Note also
        !          10493: that comments in the file begin with and end with the same strings.
        !          10494: Presumably the file contains code in a language which is like Lisp
        !          10495: (like it enough for Lisp mode to be useful) but in which comments start
        !          10496: and end in that way.  The prefix and suffix are used in the local
        !          10497: variables list to make the list appear as comments when the file is read
        !          10498: by the compiler or interpreter for that        language.
        !          10499: 
        !          10500:   The start of the local variables list must be no more than 3000
        !          10501: characters from the end of the file, and must be in the last page if the
        !          10502: file is divided into pages.  Otherwise, Emacs will not notice it is there.
        !          10503: The purpose of this is so that a stray @samp{Local Variables:}@: not in the
        !          10504: last page does not confuse Emacs, and so that visiting a long file that is
        !          10505: all one page and has no local variables list need not take the time to
        !          10506: search the whole file.
        !          10507: 
        !          10508:   You may be tempted to try to turn on Auto Fill mode with a local variable
        !          10509: list.  That is a mistake.  The choice of Auto Fill mode or not is a matter
        !          10510: of individual taste, not a matter of the contents of particular files.
        !          10511: If you want to use Auto Fill, set up major mode hooks with your @file{.emacs}
        !          10512: file to turn it on (when appropriate) for you alone (@pxref{Init File}).
        !          10513: Don't try to use a local variable list that would impose your taste on
        !          10514: everyone.
        !          10515: 
        !          10516: @node Keyboard Macros, Key Bindings, Variables, Customization
        !          10517: @section Keyboard Macros
        !          10518: 
        !          10519: @cindex keyboard macros
        !          10520:   A @dfn{keyboard macro} is a command defined by the user to abbreviate a
        !          10521: sequence of keys.  For example, if you discover that you are about to type
        !          10522: @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
        !          10523: macro to do @kbd{C-n C-d} and calling it with a repeat count of forty.
        !          10524: 
        !          10525: @c widecommands
        !          10526: @table @kbd
        !          10527: @item C-x (
        !          10528: Start defining a keyboard macro (@code{start-kbd-macro}).
        !          10529: @item C-x )
        !          10530: End the definition of a keyboard macro (@code{end-kbd-macro}).
        !          10531: @item C-x e
        !          10532: Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
        !          10533: @item C-u C-x (
        !          10534: Re-execute last keyboard macro, then add more keys to its definition.
        !          10535: @item C-x q
        !          10536: When this point is reached during macro execution, ask for confirmation
        !          10537: (@code{kbd-macro-query}).
        !          10538: @item M-x name-last-kbd-macro
        !          10539: Give a command name (for the duration of the session) to the most
        !          10540: recently defined keyboard macro.
        !          10541: @item M-x write-kbd-macro
        !          10542: Store the definition of a keyboard macro into a file.
        !          10543: @item M-x append-kbd-macro
        !          10544: Append the definition of a keyboard macro to the end of a file.
        !          10545: @end table
        !          10546: 
        !          10547:   Keyboard macros differ from ordinary Emacs commands in that they are
        !          10548: written in the Emacs command language rather than in Lisp.  This makes it
        !          10549: easier for the novice to write them, and makes them more convenient as
        !          10550: temporary hacks.  However, the Emacs command language is not powerful
        !          10551: enough as a programming language to be useful for writing anything
        !          10552: intelligent or general.  For such things, Lisp must be used.
        !          10553: 
        !          10554:   You define a keyboard macro while executing the commands which are the
        !          10555: definition.  Put differently, as you are defining a keyboard macro, the
        !          10556: definition is being executed for the first time.  This way, you can see
        !          10557: what the effects of your commands are, so that you don't have to figure
        !          10558: them out in your head.  When you are finished, the keyboard macro is
        !          10559: defined and also has been, in effect, executed once.  You can then do the
        !          10560: whole thing over again by invoking the macro.
        !          10561: 
        !          10562: @subsection Basic Use
        !          10563: 
        !          10564: @kindex C-x (
        !          10565: @kindex C-x )
        !          10566: @kindex C-x e
        !          10567: @findex start-kbd-macro
        !          10568: @findex end-kbd-macro
        !          10569: @findex call-last-kbd-macro
        !          10570:   To start defining a keyboard macro, type the @kbd{C-x (} command
        !          10571: (@code{start-kbd-macro}).  From then on, your keys continue to be
        !          10572: executed, but also become part of the definition of the macro.  @samp{Def}
        !          10573: appears in the mode line to remind you of what is going on.  When you are
        !          10574: finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
        !          10575: definition (without becoming part of it!).  For example
        !          10576: 
        !          10577: @example
        !          10578: C-x ( M-F foo C-x )
        !          10579: @end example
        !          10580: 
        !          10581: @noindent
        !          10582: defines a macro to move forward a word and then insert @samp{foo}.
        !          10583: 
        !          10584:   The macro thus defined can be invoked again with the @kbd{C-x e} command
        !          10585: (@code{call-last-kbd-macro}), which may be given a repeat count as a
        !          10586: numeric argument to execute the macro many times.  @kbd{C-x )} can also be
        !          10587: given a repeat count as an argument, in which case it repeats the macro
        !          10588: that many times right after defining it, but defining the macro counts as
        !          10589: the first repetition (since it is executed as you define it).  So, giving
        !          10590: @kbd{C-x )} an argument of 4 executes the macro immediately 3 additional
        !          10591: times.  An argument of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the
        !          10592: macro indefinitely (until it gets an error, or you type @kbd{C-g}).
        !          10593: 
        !          10594:   If you wish to repeat an operation at regularly spaced places in the
        !          10595: text, define a macro and include as part of the macro the commands to move
        !          10596: to the next place you want to use it.  For example, if you want to change
        !          10597: each line, you should position point at the start of a line, and define a
        !          10598: macro to change that line and leave point at the start of the next line.
        !          10599: Then repeating the macro will operate on successive lines.
        !          10600: 
        !          10601:   After you have terminated the definition of a keyboard macro, you can add
        !          10602: to the end of its definition by typing @kbd{C-u C-x (}.  This is equivalent
        !          10603: to plain @kbd{C-x (} followed by retyping the whole definition so far.  As
        !          10604: a consequence it re-executes the macro as previously defined.
        !          10605: 
        !          10606: @subsection Naming and Saving Keyboard Macros
        !          10607: 
        !          10608: @findex name-last-kbd-macro
        !          10609:   If you wish to save a keyboard macro for longer than until you define the
        !          10610: next one, you must give it a name or install it on a command sequence.  To
        !          10611: give the macro a name, use @kbd{M-x name-last-kbd-macro}.  This reads a
        !          10612: name as an argument using the minibuffer and defines that name to execute
        !          10613: the macro.  The macro name is a Lisp symbol, and defining it in this way
        !          10614: makes it a valid command name for calling with @kbd{M-x} or for binding a
        !          10615: key to with @code{global-set-key} (@pxref{Keymaps}).
        !          10616: 
        !          10617: @findex write-kbd-macro
        !          10618: @findex append-kbd-macro
        !          10619:   Once a macro has a command name, you can save its definition in a file.
        !          10620: Then it can be used in another editing session.
        !          10621: 
        !          10622: @example
        !          10623: M-x write-kbd-macro @key{RET} @var{macroname} @key{RET} @var{file} @key{RET}
        !          10624: @end example
        !          10625: 
        !          10626: @noindent
        !          10627: writes a Lisp expression for the definition of the keyboard macro named
        !          10628: @var{macroname} into the file @var{file}, replacing any previous contents.
        !          10629: The file can be loaded with @code{load} (@pxref{Lisp Libraries}).
        !          10630: The command @code{append-kbd-macro} is similar, but adds the definition
        !          10631: to the end of the file, in addition to the previous contents.  You might
        !          10632: want to add a macro in this way to your init file @file{~/.emacs}; then
        !          10633: it will automatically be defined when you run Emacs again.
        !          10634: 
        !          10635: @subsection Executing Macros with Variations
        !          10636: 
        !          10637: @kindex C-x q
        !          10638: @findex kbd-macro-query
        !          10639:   Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect similar
        !          10640: to that of @code{query-replace}, where the macro asks you each time around
        !          10641: whether to make a change.  When you are defining the macro, type @kbd{C-x
        !          10642: q} at the point where you want the query to occur.  During macro
        !          10643: definition, the @kbd{C-x q} does nothing, but when the macro is invoked the
        !          10644: @kbd{C-x q} reads a character from the terminal to decide whether to
        !          10645: continue.
        !          10646: 
        !          10647:   The special answers are @key{SPC}, @key{DEL}, @kbd{C-d}, @kbd{C-l} and
        !          10648: @kbd{C-r}.  Any other character terminates execution of the keyboard macro
        !          10649: and is then read as a command.  @key{SPC} means to continue.  @key{DEL}
        !          10650: means to skip the remainder of this repetition of the macro, starting again
        !          10651: from the beginning in the next repetition.  @kbd{C-d} means to skip the
        !          10652: remainder of this repetition and cancel further repetition.  @kbd{C-l}
        !          10653: clears the screen and asks you again for a character to say what to do.
        !          10654: @kbd{C-r} enters a recursive editing level, in which you can perform
        !          10655: editing which is not part of the macro.  When you exit the recursive edit
        !          10656: using @kbd{C-M-c}, you are asked again how to continue with the keyboard
        !          10657: macro.  If you type a @key{SPC} at this time, the rest of the macro
        !          10658: definition is executed.  It is up to you to leave point and the text in a
        !          10659: state such that the rest of the macro will do what you want.@refill
        !          10660: 
        !          10661:   @kbd{C-u C-x q}, @kbd{C-x q} with a numeric argument, performs a different
        !          10662: function.  It enters a recursive edit reading input from the keyboard, both
        !          10663: when you type it during the definition of the macro, and when it is
        !          10664: executed from the macro.  During definition, the editing you do inside the
        !          10665: recursive edit does not become part of the macro.  During macro execution,
        !          10666: the recursive edit gives you a chance to do some particularized editing.
        !          10667: @xref{Recursive Edit}.
        !          10668: 
        !          10669: @node Key Bindings, Syntax, Keyboard Macros, Customization
        !          10670: @section Customizing Key Bindings
        !          10671: 
        !          10672:   This section deals with the @dfn{keymaps} which define the bindings
        !          10673: between keys and functions, and says how you can customize these bindings.
        !          10674: @cindex command
        !          10675: @cindex function
        !          10676: @cindex command name
        !          10677: 
        !          10678:   A command is a Lisp function whose definition provides for interactive
        !          10679: use.  Like every Lisp function, a command has a function name, a Lisp
        !          10680: symbol whose name usually consists of lower case letters and dashes.
        !          10681: 
        !          10682:   The bindings between characters and command functions are recorded in
        !          10683: data structures called @dfn{keymaps}.  Emacs has many of these.  One, the
        !          10684: @dfn{global} keymap, defines the meanings of the single keys that are
        !          10685: defined regardless of major mode.  Each major mode has another keymap, its
        !          10686: @dfn{local keymap}, which contains overriding definitions for the single
        !          10687: keys that are to be redefined in that mode.  Finally, each prefix key has a
        !          10688: keymap which defines the key sequences that start with that prefix.
        !          10689: 
        !          10690: @menu
        !          10691: * Keymaps::    Definition of the keymap data structure.
        !          10692: * Rebinding::  How to redefine one key's meaning conveniently.
        !          10693: * Disabling::  Disabling a command means confirmation is required
        !          10694:                 before it can be executed.  This is done to protect
        !          10695:                 beginners from surprises.
        !          10696: @end menu
        !          10697: 
        !          10698: @node Keymaps, Rebinding, Key Bindings, Key Bindings
        !          10699: @subsection Keymaps
        !          10700: @cindex keymap
        !          10701: 
        !          10702: @cindex global keymap
        !          10703: @vindex global-map
        !          10704:   The bindings between characters and command functions are recorded in
        !          10705: data structures called @dfn{keymaps}.  Emacs has many of these.  One, the
        !          10706: @dfn{global} keymap, defines the meanings of the single keys that are
        !          10707: defined regardless of major mode.  It is the value of the variable
        !          10708: @code{global-map}.
        !          10709: 
        !          10710: @cindex local keymap
        !          10711: @vindex c-mode-map
        !          10712: @vindex lisp-mode-map
        !          10713:   Each major mode has another keymap, its @dfn{local keymap}, which
        !          10714: contains overriding definitions for the single keys that are to be
        !          10715: redefined in that mode.  Each buffer records which local keymap is
        !          10716: installed for it at any time, and the current buffer's local keymap is the
        !          10717: only one that directly affects command execution.  The local keymaps for
        !          10718: Lisp mode, C mode, and many other major modes always exist even when not in
        !          10719: use.  They are the values of the variables @code{lisp-mode-map},
        !          10720: @code{c-mode-map}, and so on.  For major modes less often used, the local
        !          10721: keymap is sometimes constructed only when the mode is used for the first
        !          10722: time in a session.  This is to save space.
        !          10723: 
        !          10724: @vindex minibuffer-local-map
        !          10725: @vindex minibuffer-local-ns-map
        !          10726: @vindex minibuffer-local-completion-map
        !          10727: @vindex minibuffer-local-must-match-map
        !          10728:   There are local keymaps for the minibuffer too; they contain various
        !          10729: completion and exit commands.
        !          10730: 
        !          10731: @itemize @bullet
        !          10732: @item
        !          10733: @code{minibuffer-local-map} is used for ordinary input (no completion).
        !          10734: @item
        !          10735: @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
        !          10736: just like @key{RET}.  This is used mainly for Mocklisp compatibility.
        !          10737: @item
        !          10738: @code{minibuffer-local-completion-map} is for permissive completion.
        !          10739: @item
        !          10740: @code{minibuffer-local-must-match-map} is for strict completion and
        !          10741: for cautious completion.
        !          10742: @end itemize
        !          10743: 
        !          10744: @vindex ctl-x-map
        !          10745: @vindex help-map
        !          10746: @vindex esc-map
        !          10747:   Finally, each prefix key has a keymap which defines the key sequences
        !          10748: that start with it.  For example, @code{ctl-x-map} is the keymap used for
        !          10749: characters following a @kbd{C-x}, and @code{help-map} is the keymap used
        !          10750: for characters following a @kbd{C-h}.  @code{esc-map} is the keymap used
        !          10751: for characters following @key{ESC}, and therefore for all Meta characters
        !          10752: (see below).  In fact, the definition of a prefix key is just the keymap to
        !          10753: use for looking up the following character.  Actually, the definition is
        !          10754: sometimes a Lisp symbol whose function definition is the following character
        !          10755: keymap.  The effect is the same, but it provides a command name for the
        !          10756: prefix key that can be used as a description of what the prefix key is for.
        !          10757: Thus, the binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose
        !          10758: function definition is the keymap for @kbd{C-x} commands, the value of
        !          10759: @code{ctl-x-map}.@refill
        !          10760: 
        !          10761:   Prefix key definitions of this sort can appear in either the global map
        !          10762: or a local map.  The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC}
        !          10763: as prefix keys appear in the global map, so these prefix keys are always
        !          10764: available.  Major modes can locally redefine a key as a prefix by putting
        !          10765: a prefix key definition for it in the local map.@refill
        !          10766: 
        !          10767:   A mode can also put a prefix definition of a global prefix character such
        !          10768: as @kbd{C-x} into its local map.  This is how major modes override the
        !          10769: definitions of certain keys that start with @kbd{C-x}.  This case is
        !          10770: special, because the local definition does not entirely replace the global
        !          10771: one.  When both the global and local definitions of a key are other
        !          10772: keymaps, the next character is looked up in both keymaps, with the local
        !          10773: definition overriding the global one as usual.  So, the character after the
        !          10774: @kbd{C-x} is looked up in both the major mode's own keymap for redefined
        !          10775: @kbd{C-x} commands and in @code{ctl-x-map}.  If the major mode's own keymap
        !          10776: for @kbd{C-x} commands contains @code{nil}, the definition from the global
        !          10777: keymap for @kbd{C-x} commands is used.@refill
        !          10778: 
        !          10779: @cindex sparse keymap
        !          10780:   A keymap is actually a Lisp object.  The simplest form of keymap is a
        !          10781: Lisp vector of length 128.  The binding for a character in such a keymap is
        !          10782: found by indexing into the vector with the character as an index.  A keymap
        !          10783: can also be a Lisp list whose car is the symbol @code{keymap} and whose
        !          10784: remaining elements are pairs of the form @code{(@var{char} . @var{binding})}.
        !          10785: Such lists are called @dfn{sparse keymaps} because they are used when most
        !          10786: of the characters' entries will be @code{nil}.  Sparse keymaps are used
        !          10787: mainly for prefix characters.
        !          10788: 
        !          10789:   Keymaps are only of length 128, so what about Meta characters, whose
        !          10790: codes are from 128 to 255?  A key that contains a Meta character actually
        !          10791: represents it as a sequence of two characters, the first of which is
        !          10792: @key{ESC}.  So the key @kbd{M-a} is really represented as @kbd{@key{ESC}
        !          10793: a}, and its binding is found at the slot for @samp{a} in
        !          10794: @code{esc-map}.@refill
        !          10795: 
        !          10796: @node Rebinding, Disabling, Keymaps, Key Bindings
        !          10797: @subsection Changing Key Bindings Interactively
        !          10798: 
        !          10799:   The way to redefine an Emacs key is to change its entry in a keymap.
        !          10800: You can change the global keymap, in which case the change is effective in
        !          10801: all major modes (except those that have their own overriding local
        !          10802: definitions for the same key).  Or you can change the current buffer's
        !          10803: local map, which affects all buffers using the same major mode.
        !          10804: @findex global-set-key
        !          10805: @findex local-set-key
        !          10806: 
        !          10807: @table @kbd
        !          10808: @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
        !          10809: Defines @var{key} globally to run @var{cmd}.
        !          10810: @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
        !          10811: Defines @var{key} locally (in the major mode now in effect) to run
        !          10812: @var{cmd}.
        !          10813: @end table
        !          10814: 
        !          10815:   For example,
        !          10816: 
        !          10817: @example
        !          10818: M-x global-set-key @key{RET} C-f next-line @key{RET}
        !          10819: @end example
        !          10820: 
        !          10821: @noindent
        !          10822: would redefine @kbd{C-f} to move down a line.  The fact that @var{cmd} is
        !          10823: read second makes it serve as a kind of confirmation for @var{key}.
        !          10824: 
        !          10825:   These functions offer no way to specify a particular prefix keymap as the
        !          10826: one to redefine in, but that is not necessary, as you can include prefixes
        !          10827: in @var{key}.  @var{key} is read by reading characters one by one until
        !          10828: they amount to a complete key (that is, not a prefix key).  Thus, if you
        !          10829: type @kbd{C-f} for @var{key}, that's the end; the minibuffer is entered
        !          10830: immediately to read @var{cmd}.  But if you type @kbd{C-x}, another
        !          10831: character is read; if that is @kbd{4}, another character is read, and so
        !          10832: on.  For example,@refill
        !          10833: 
        !          10834: @example
        !          10835: M-x global-set-key @key{RET} C-x 4 $ dictionary-other-window @key{RET}
        !          10836: @end example
        !          10837: 
        !          10838: @noindent
        !          10839: would redefine @kbd{C-x 4 $} to run the (fictitious) command
        !          10840: @code{dictionary-other-window}.
        !          10841: 
        !          10842: @findex define-key
        !          10843:   The most general way to modify a keymap is the function @code{define-key},
        !          10844: used in Lisp code (such in your @file{.emacs} file).  @code{define-key}
        !          10845: takes three arguments: the keymap, the key to modify in it, and the new
        !          10846: definition.  @xref{Init File}, for an example.
        !          10847: 
        !          10848: @node Disabling,, Rebinding, Key Bindings
        !          10849: @subsection Disabling Commands
        !          10850: @cindex disabled command
        !          10851: 
        !          10852:   Disabling a command marks the command as requiring confirmation before it
        !          10853: can be executed.  The purpose of disabling a command is to prevent
        !          10854: beginning users from executing it by accident and being confused.
        !          10855: 
        !          10856:   The direct mechanism for disabling a command is to have a non-@code{nil}
        !          10857: @code{disabled} property on the Lisp symbol for the command.  These
        !          10858: properties are normally set up by the user's @file{.emacs} file with
        !          10859: Lisp expressions such as
        !          10860: 
        !          10861: @example
        !          10862: (put 'delete-region 'disabled t)
        !          10863: @end example
        !          10864: 
        !          10865: @findex disable-command
        !          10866: @findex enable-command
        !          10867:   You can make a command disabled either by editing the @file{.emacs} file
        !          10868: directly or with the command @kbd{M-x disable-command}, which edits the
        !          10869: @file{.emacs} file for you.  @xref{Init File}.
        !          10870: 
        !          10871:   Attempting to invoke a disabled command interactively in Emacs causes the
        !          10872: display of a window containing the command's name, its documentation, and
        !          10873: some instructions on what to do immediately; then Emacs asks for input
        !          10874: saying whether to execute the command as requested, enable it and execute,
        !          10875: or cancel it.  If you decide to enable the command, you are asked whether to
        !          10876: do this permanently or just for the current session.  Enabling permanently
        !          10877: works by automatically editing your @file{.emacs} file.  You can use
        !          10878: @kbd{M-x enable-command} to enable a command permanently without
        !          10879: executing it.
        !          10880: 
        !          10881:   Whether a command is disabled is independent of what key is used to
        !          10882: invoke it; it also applies if the command is invoked using @kbd{M-x}.
        !          10883: Disabling a command has no effect on calling it as a function from Lisp
        !          10884: programs.
        !          10885: 
        !          10886: @node Syntax, Init File, Key Bindings, Customization
        !          10887: @section The Syntax Table
        !          10888: @cindex syntax table
        !          10889: 
        !          10890:   All the Emacs commands which parse words or balance parentheses are
        !          10891: controlled by the @dfn{syntax table}.  The syntax table says which
        !          10892: characters are opening delimiters, which are parts of words, which are
        !          10893: string quotes, and so on.  Actually, each major mode has its own syntax
        !          10894: table (though sometimes related major modes use the same one) which it
        !          10895: installs in each buffer that uses that major mode.  The syntax table
        !          10896: installed in the current buffer is the one that all commands use.  So we
        !          10897: will call it ``the syntax table''.  A syntax table is a Lisp object, a
        !          10898: vector of length 256 whose elements are numbers.
        !          10899: 
        !          10900:   The syntax table entry for a character holds six pieces of information:
        !          10901: 
        !          10902: @itemize @bullet
        !          10903: @item
        !          10904: The syntactic class of the character, represented as a small integer.
        !          10905: @item
        !          10906: The matching delimiter, for delimiter characters only.
        !          10907: The matching delimiter of @samp{(} is @samp{)}, and vice versa.
        !          10908: @item
        !          10909: A flag saying whether the character is the first character of a
        !          10910: two-character comment starting sequence.
        !          10911: @item
        !          10912: A flag saying whether the character is the second character of a
        !          10913: two-character comment starting sequence.
        !          10914: @item
        !          10915: A flag saying whether the character is the first character of a
        !          10916: two-character comment ending sequence.
        !          10917: @item
        !          10918: A flag saying whether the character is the second character of a
        !          10919: two-character comment ending sequence.
        !          10920: @end itemize
        !          10921: 
        !          10922:   The syntactic classes are stored internally as small integers, but are
        !          10923: usually described to or by the user with characters.  For example, @samp{(}
        !          10924: is used to specify the syntactic class of opening delimiters.  Here is a
        !          10925: table of syntactic classes, with the characters that specify them.
        !          10926: 
        !          10927: @table @samp
        !          10928: @item @w{ }
        !          10929: The class of whitespace characters.
        !          10930: @item w
        !          10931: The class of word-constituent characters.
        !          10932: @item _
        !          10933: The class of characters that are part of symbol names but not words.
        !          10934: This class is represented by @samp{_} because the character @samp{_}
        !          10935: has this class in both C and Lisp.
        !          10936: @item .
        !          10937: The class of punctuation characters that do not fit into any other
        !          10938: special class.
        !          10939: @item (
        !          10940: The class of opening delimiters. 
        !          10941: @item )
        !          10942: The class of closing delimiters. 
        !          10943: @item '
        !          10944: The class of expression-adhering characters.  These characters are
        !          10945: part of a symbol if found within or adjacent to one, and are part
        !          10946: of a following expression if immediately preceding one, but are like
        !          10947: whitespace if surrounded by whitespace.
        !          10948: @item "
        !          10949: The class of string-quote characters.  They match each other in pairs,
        !          10950: and the characters within the pair all lose their syntactic
        !          10951: significance except for the @samp{\} and @samp{/} classes of escape
        !          10952: characters, which can be used to include a string-quote inside the
        !          10953: string.
        !          10954: @item $
        !          10955: The class of self-matching delimiters.  This is intended for @TeX{}'s
        !          10956: @samp{$}, which is used both to enter and leave math mode.  Thus,
        !          10957: a pair of matching @samp{$} characters surround each piece of math mode
        !          10958: @TeX{} input.  A pair of adjacent @samp{$} characters act like a single
        !          10959: one for purposes of matching
        !          10960: 
        !          10961: @item /
        !          10962: The class of escape characters that always just deny the following
        !          10963: character its special syntactic significance.  The character after one
        !          10964: of these escapes is always treated as alphabetic.
        !          10965: @item \
        !          10966: The class of C-style escape characters.  In practice, these are
        !          10967: treated just like @samp{/}-class characters, because the extra
        !          10968: possibilities for C escapes (such as being followed by digits) have no
        !          10969: effect on where the containing expression ends.
        !          10970: @item <
        !          10971: The class of comment-starting characters.  Only single-character
        !          10972: comment starters (such as @samp{;} in Lisp mode) are represented this
        !          10973: way.
        !          10974: @item >
        !          10975: The class of comment-ending characters.  Newline has this syntax in
        !          10976: Lisp mode.
        !          10977: @end table
        !          10978: 
        !          10979: @vindex parse-sexp-ignore-comments
        !          10980:   The characters flagged as part of two-character comment delimiters can
        !          10981: have other syntactic functions most of the time.  For example, @samp{/} and
        !          10982: @samp{*} in C code, when found separately, have nothing to do with
        !          10983: comments.  The comment-delimiter significance overrides when the pair of
        !          10984: characters occur together in the proper order.  Only the list and sexp
        !          10985: commands use the syntax table to find comments; the commands specifically
        !          10986: for comments have other variables that tell them where to find comments.
        !          10987: And the list and sexp commands notice comments only if
        !          10988: @code{parse-sexp-ignore-comments} is non-@code{nil}.  This variable is set
        !          10989: to @code{nil} in modes where comment-terminator sequences are liable to
        !          10990: appear where there is no comment; for example, in Lisp mode where the
        !          10991: comment terminator is a newline but not every newline ends a comment.
        !          10992: 
        !          10993: @findex modify-syntax-entry
        !          10994:   @kbd{M-x modify-syntax-entry} is the command to change a character's
        !          10995: syntax.  It can be used interactively, and is also the means used by major
        !          10996: modes to initialize their own syntax tables.  Its first argument is the
        !          10997: character to change.  The second argument is a string that specifies the
        !          10998: new syntax.  When called from Lisp code, there is a third, optional
        !          10999: argument, which specifies the syntax table in which to make the change.  If
        !          11000: not supplied, or if this command is called interactively, the third
        !          11001: argument defaults to the current buffer's syntax table.
        !          11002: 
        !          11003: @enumerate
        !          11004: @item
        !          11005: The first character in the string specifies the syntactic class.  It
        !          11006: is one of the characters in the previous table.
        !          11007: 
        !          11008: @item
        !          11009: The second character is the matching delimiter.  For a character that
        !          11010: is not an opening or closing delimiter, this should be a space, or may
        !          11011: be omitted if no following characters are needed.
        !          11012: 
        !          11013: @item
        !          11014: The remaining characters are flags.  The flag characters allowed are
        !          11015: 
        !          11016: @table @samp
        !          11017: @item 1
        !          11018: Flag this character as the first of a two-character comment starting sequence.
        !          11019: @item 2
        !          11020: Flag this character as the second of a two-character comment starting sequence.
        !          11021: @item 3
        !          11022: Flag this character as the first of a two-character comment ending sequence.
        !          11023: @item 4
        !          11024: Flag this character as the second of a two-character comment ending sequence.
        !          11025: @end table
        !          11026: @end enumerate
        !          11027: 
        !          11028: @kindex C-h s
        !          11029: @findex describe-syntax
        !          11030:   A description of the contents of the current syntax table can be
        !          11031: displayed with @kbd{C-h s} (@code{describe-syntax}).  The description of
        !          11032: each character includes both the string you would have to give to
        !          11033: @code{modify-syntax-entry} to set up that character's current syntax, and
        !          11034: some English to explain that string if necessary.
        !          11035: 
        !          11036: @node Init File,, Syntax, Customization
        !          11037: @section The Init File, .emacs
        !          11038: @cindex init file
        !          11039: 
        !          11040:   When Emacs is started, it normally loads the file @file{.emacs} in your
        !          11041: home directory.  This file, if it exists, should contain Lisp code.
        !          11042: Here we describe how to do certain common things in the @file{.emacs} file.
        !          11043: 
        !          11044:   The @file{.emacs} file contains one or more Lisp function call
        !          11045: expressions.  Each of these consists of a function name followed by
        !          11046: arguments, all surrounded by parentheses.  For example, @code{(setq
        !          11047: default-fill-column 60)} represents a call to the function @code{setq}
        !          11048: which is used to set the variable @code{default-fill-column}
        !          11049: (@pxref{Filling}) to 60.
        !          11050: 
        !          11051:   The second argument to @code{setq} is an expression for the new value of
        !          11052: the variable.  This can be a constant, a variable, or a function call
        !          11053: expression.  In @file{.emacs}, constants are used most of the time.  They can be:
        !          11054: 
        !          11055: @table @asis
        !          11056: @item Numbers:
        !          11057: Numbers are written in decimal, with an optional initial minus sign.
        !          11058: @item Strings:
        !          11059: Lisp string syntax is the same as C string syntax with a few extra
        !          11060: features.  First, newlines and any other characters may be present
        !          11061: literally in strings.  Second, @samp{\e} may be used to stand for the
        !          11062: character @key{ESC}.  Third, @samp{\C-} can be used as a prefix for a
        !          11063: control character, as in @samp{\C-s} for ASCII Control-S, and
        !          11064: @samp{\M-} can be used as a prefix for a meta character, as in
        !          11065: @samp{\M-a} for Meta-A or @samp{\M-\C-a} for Control-Meta-A.@refill
        !          11066: @item Characters:
        !          11067: Lisp character constant syntax consists of a @samp{?} followed by
        !          11068: either a character or an escape sequence starting with @samp{\}.
        !          11069: Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
        !          11070: strings and characters are not interchangeable in Lisp; some contexts
        !          11071: require one and some contexts require the other.
        !          11072: @item True:
        !          11073: @code{t} stands for `true'.
        !          11074: @item False:
        !          11075: @code{nil} stands for `false'.
        !          11076: @item Other Lisp objects:
        !          11077: Write a single-quote (') followed by the Lisp object you want.
        !          11078: @end table
        !          11079: 
        !          11080:   Here are some examples of doing certain commonly desired things with
        !          11081: Lisp expressions:
        !          11082: 
        !          11083: @itemize @bullet
        !          11084: @item
        !          11085: Make searches case sensitive:
        !          11086: 
        !          11087: @example
        !          11088: (setq default-case-fold-search nil)
        !          11089: @end example
        !          11090: 
        !          11091: Here we have a variable whose value is normally @code{t} for `true'
        !          11092: and the alternative is @code{nil} for `false'.
        !          11093: 
        !          11094: @item
        !          11095: Make Text mode the default mode for new buffers:
        !          11096: 
        !          11097: @example
        !          11098: (setq default-major-mode 'text-mode)
        !          11099: @end example
        !          11100: 
        !          11101: Note that @code{text-mode} is used because it is the command for entering
        !          11102: the mode we want.  A single-quote is written before it to make a symbol
        !          11103: constant; otherwise, @code{text-mode} would be treated as a variable name.
        !          11104: 
        !          11105: @item
        !          11106: Turn on Auto Fill mode automatically in Text mode and related modes:
        !          11107: 
        !          11108: @example
        !          11109: (setq text-mode-hook
        !          11110:   '(lambda () (auto-fill-mode 1)))
        !          11111: @end example
        !          11112: 
        !          11113: Here we have a variable whose value should be a Lisp function.  The
        !          11114: function we supply is a list starting with @code{lambda}, and a single
        !          11115: quote is written in front of it to make it (for the purpose of this
        !          11116: @code{setq}) a list constant rather than an expression.  Lisp functions
        !          11117: are not explained here, but for mode hooks it is enough to know that
        !          11118: @code{(auto-fill-mode 1)} is an expression that will be executed when
        !          11119: Text mode is entered, and you could replace it with any other expression
        !          11120: that you like, or with several expressions in a row.
        !          11121: 
        !          11122: @example
        !          11123: (setq text-mode-hook 'turn-on-auto-fill)
        !          11124: @end example
        !          11125: 
        !          11126: This is another way to accomplish the same result.
        !          11127: @code{turn-on-auto-fill} is a symbol whose function definition is
        !          11128: @code{(lambda () (auto-fill-mode 1))}.
        !          11129: 
        !          11130: @item
        !          11131: Load the compiled Lisp file @file{foo.elc}.
        !          11132: 
        !          11133: @example
        !          11134: (load "foo")
        !          11135: @end example
        !          11136: 
        !          11137: @item
        !          11138: Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
        !          11139: 
        !          11140: @example
        !          11141: (global-set-key "\C-xl" 'make-symbolic-link)
        !          11142: @end example
        !          11143: 
        !          11144: Note once again the single-quote used to refer to the symbol
        !          11145: @code{make-symbolic-link} instead of its value as a variable.
        !          11146: 
        !          11147: @item
        !          11148: Do the same thing for C mode only.
        !          11149: 
        !          11150: @example
        !          11151: (define-key c-mode-map "\C-xl" 'make-symbolic-link)
        !          11152: @end example
        !          11153: 
        !          11154: @item
        !          11155: Make @kbd{C-x p} undefined.
        !          11156: 
        !          11157: @example
        !          11158: (global-unset-key "\C-xp")
        !          11159: @end example
        !          11160: 
        !          11161: One reason to undefine a key is so that you can make it a prefix.
        !          11162: Simply defining @kbd{C-x p @var{anything}} would make @kbd{C-x p}
        !          11163: a prefix, provided it is not otherwise defined.
        !          11164: 
        !          11165: @item
        !          11166: Make @samp{$} have the syntax of punctuation in Text mode.
        !          11167: Note the use of a character constant for @samp{$}.
        !          11168: 
        !          11169: @example
        !          11170: (modify-syntax-entry ?\$ "." text-mode-syntax-table)
        !          11171: @end example
        !          11172: 
        !          11173: @item
        !          11174: Enable the use of the command @code{eval-expression} without confirmation.
        !          11175: 
        !          11176: @example
        !          11177: (put 'eval-expression 'disabled nil)
        !          11178: @end example
        !          11179: @end itemize
        !          11180: 
        !          11181: @iftex
        !          11182: @chapter Correcting Mistakes (Yours or Emacs's)
        !          11183: 
        !          11184:   If you type an Emacs command you did not intend, the results are often
        !          11185: mysterious.  This chapter tells what you can do to cancel your mistake or
        !          11186: recover from a mysterious situation.  Emacs bugs and system crashes are
        !          11187: also considered.
        !          11188: @end iftex
        !          11189: 
        !          11190: @node Quitting, Lossage, Customization, Top
        !          11191: @section Quitting and Aborting
        !          11192: @cindex quitting
        !          11193: 
        !          11194: @table @kbd
        !          11195: @item C-g
        !          11196: Quit.  Cancel running or partially typed command.
        !          11197: @item C-]
        !          11198: Abort recursive editing level and cancel the command which invoked it
        !          11199: (@code{abort-recursive-edit}).
        !          11200: @item M-x top-level
        !          11201: Abort all recursive editing levels that are currently executing.
        !          11202: @item C-x u
        !          11203: Cancel an already-executed command, usually (@code{undo}).
        !          11204: @end table
        !          11205: 
        !          11206:   There are two ways of cancelling commands which are not finished
        !          11207: executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
        !          11208: or @kbd{M-x top-level}.  Quitting is cancelling a partially typed command
        !          11209: or one which is already running.  Aborting is getting out of a recursive
        !          11210: editing level and cancelling the command that invoked the recursive edit.
        !          11211: 
        !          11212: @cindex quitting
        !          11213: @cindex C-g
        !          11214:   Quitting with @kbd{C-g} is used for getting rid of a partially typed
        !          11215: command, or a numeric argument that you don't want.  It also stops a
        !          11216: running command in the middle in a relatively safe way, so you can use it
        !          11217: if you accidentally give a command which takes a long time.  In particular,
        !          11218: it is safe to quit out of killing; either your text will @var{all} still be
        !          11219: there, or it will @var{all} be in the kill ring (or maybe both).  Quitting
        !          11220: an incremental search does special things documented under searching; in
        !          11221: general, it may take two successive @kbd{C-g} characters to get out of a
        !          11222: search.  @kbd{C-g} works by setting the variable @code{quit-flag} to
        !          11223: @code{t} the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
        !          11224: frequently and quits if it is non-@code{nil}.  @kbd{C-g} is only actually
        !          11225: executed as a command if it is typed while Emacs is waiting for input.
        !          11226: 
        !          11227:   If you quit twice in a row before the first @kbd{C-g} is recognized, you
        !          11228: activate the ``emergency escape'' feature and return to the shell.
        !          11229: @xref{Emergency Escape}.
        !          11230: 
        !          11231: @cindex recursive editing level
        !          11232: @cindex aborting
        !          11233: @findex abort-recursive-edit
        !          11234: @kindex C-]
        !          11235:   Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get out
        !          11236: of a recursive editing level and cancel the command which invoked it.
        !          11237: Quitting with @kbd{C-g} does not do this, and could not do this, because it
        !          11238: is used to cancel a partially typed command @i{within} the recursive
        !          11239: editing level.  Both operations are useful.  For example, if you are in the
        !          11240: Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
        !          11241: numeric argument, you can cancel that argument with @kbd{C-g} and remain in
        !          11242: the debugger.
        !          11243: 
        !          11244: @findex top-level
        !          11245:   The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
        !          11246: commands to get you out of all the levels of subsystems and recursive edits
        !          11247: that you are in.  @kbd{C-]} gets you out one level at a time, but @kbd{M-x
        !          11248: top-level} goes out all levels at once.  Both @kbd{C-]} and @kbd{M-x
        !          11249: top-level} are like all other commands, and unlike @kbd{C-g}, in that they
        !          11250: are effective only when Emacs is ready for a command.  @kbd{C-]} is an
        !          11251: ordinary key and has its meaning only because of its binding in the keymap.
        !          11252: 
        !          11253:   @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling
        !          11254: a command, but you can think of it as cancelling a command already finished
        !          11255: executing.  @xref{Undo}.
        !          11256: 
        !          11257: @node Lossage, Bugs, Quitting, Top
        !          11258: @section Dealing with Emacs Trouble
        !          11259: 
        !          11260:   This section describes various conditions in which Emacs fails to work,
        !          11261: and how to recognize them and correct them.
        !          11262: 
        !          11263: @menu
        !          11264: * Stuck Recursive::    `[...]' in mode line around the parentheses
        !          11265: * Screen Garbled::     Garbage on the screen
        !          11266: * Text Garbled::       Garbage in the text
        !          11267: * Unasked-for Search:: Spontaneous entry to incremental search
        !          11268: * Emergency Escape::   Emergency escape---
        !          11269:                         What to do if Emacs stops responding
        !          11270: * Total Frustration::  When you are at your wits' end.
        !          11271: @end menu
        !          11272: 
        !          11273: @node Stuck Recursive, Screen Garbled, Lossage, Lossage
        !          11274: @subsection Recursive Editing Levels
        !          11275: 
        !          11276:   Recursive editing levels are important and useful features of Emacs, but
        !          11277: they can seem like malfunctions to the user who does not understand them.
        !          11278: 
        !          11279:   If the mode line has square brackets @samp{[@dots{}]} around the parentheses
        !          11280: that contain the names of the major and minor modes, you have entered a
        !          11281: recursive editing level.  If you did not do this on purpose, or if you
        !          11282: don't understand what that means, you should just get out of the recursive
        !          11283: editing level.  To do so, type @kbd{M-x top-level}.  This is called getting
        !          11284: back to top level.  @xref{Recursive Edit}.
        !          11285: 
        !          11286: @node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
        !          11287: @subsection Garbage on the Screen
        !          11288: 
        !          11289:   If the data on the screen looks wrong, the first thing to do is see
        !          11290: whether the text is really wrong.  Type @kbd{C-l}, to redisplay the entire
        !          11291: screen.  If it appears correct after this, the problem was entirely in the
        !          11292: previous screen update.
        !          11293: 
        !          11294:   Display updating problems often result from an incorrect termcap entry
        !          11295: for the terminal you are using.  The file @file{etc/TERMS} gives the fixes
        !          11296: for known problems of this sort.  @file{INSTALL} contains general advice
        !          11297: for these problems in one of its sections.  Very likely there is simply
        !          11298: insufficient padding for certain display operations.  To investigate the
        !          11299: possibility that you have this sort of problem, try Emacs on another
        !          11300: terminal made by a different manufacturer.  If problems happen frequently
        !          11301: on one kind of terminal but not another kind, it is likely to be a bad
        !          11302: termcap entry, though it could also be due to a bug in Emacs that appears
        !          11303: for terminals that have or that lack specific features.
        !          11304: 
        !          11305: @node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
        !          11306: @subsection Garbage in the Text
        !          11307: 
        !          11308:   If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
        !          11309: using @kbd{C-x u} until it gets back to a state you consider correct.  Also
        !          11310: try @kbd{C-h l} to find out what command you typed to produce the observed
        !          11311: results.
        !          11312: 
        !          11313:   If a large portion of text appears to be missing at the beginning or
        !          11314: end of the buffer, check for the word @samp{Narrow} in the mode line.
        !          11315: If it appears, the text is still present, but marked off-limits.
        !          11316: To make it visible again, type @kbd{C-x w}.  @xref{Narrowing}.
        !          11317: 
        !          11318: @node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
        !          11319: @subsection Spontaneous Entry to Incremental Search
        !          11320: 
        !          11321:   If Emacs spontaneously displays @samp{I-search:} at the bottom of the
        !          11322: screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
        !          11323: according to the badly designed xon/xoff ``flow control'' protocol.  You
        !          11324: should try to prevent this by putting the terminal in a mode where it will
        !          11325: not use flow control or giving it enough padding that it will never send a
        !          11326: @kbd{C-s}.  If that cannot be done, you must tell Emacs to expect flow
        !          11327: control to be used, until you can get a properly designed terminal.
        !          11328: 
        !          11329:   Information on how to do these things can be found in the file
        !          11330: @file{INSTALL} in the Emacs distribution.
        !          11331: 
        !          11332: @node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
        !          11333: @subsection Emergency Escape
        !          11334: 
        !          11335:   Because at times there have been bugs causing Emacs to loop without
        !          11336: checking @code{quit-flag}, a special feature causes Emacs to be suspended
        !          11337: immediately if you type a second @kbd{C-g} while the flag is already set.
        !          11338: So you can always get out of GNU Emacs.  Normally Emacs recognizes and
        !          11339: clears @code{quit-flag} (and quits!)  quickly enough to prevent this from
        !          11340: happening.
        !          11341: 
        !          11342:   When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
        !          11343: asks two questions before going back to what it had been doing:
        !          11344: 
        !          11345: @example
        !          11346: Checkpoint?
        !          11347: Abort (and dump core)?
        !          11348: @end example
        !          11349: 
        !          11350: @noindent
        !          11351: Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
        !          11352: 
        !          11353:   Saying @kbd{y} to @samp{Checkpoint?} causes immediate auto-saving of all
        !          11354: modified buffers in which auto-saving is enabled.
        !          11355: 
        !          11356:   Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be
        !          11357: executed, dumping core.  This is to enable a wizard to figure out why Emacs
        !          11358: was failing to quit in the first place.  Execution does not continue
        !          11359: after a core dump.  If you answer @kbd{n}, execution does continue.  With
        !          11360: luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally.
        !          11361: If not, and you type another @kbd{C-g}, it is suspended again.
        !          11362: 
        !          11363:   If Emacs is not really hung, just slow, you may invoke the double
        !          11364: @kbd{C-g} feature without really meaning to.  Then just resume and answer
        !          11365: @kbd{n} to both questions, and you will arrive at your former state.
        !          11366: Presumably the quit you requested will happen soon.
        !          11367: 
        !          11368: @node Total Frustration,, Emergency Escape, Lossage
        !          11369: @subsection Help for Total Frustration
        !          11370: @cindex Eliza
        !          11371: @cindex doctor
        !          11372: 
        !          11373:   If using Emacs (or something else) becomes terribly frustrating and none
        !          11374: of the techniques described above solve the problem, Emacs can still help
        !          11375: you.
        !          11376: 
        !          11377:   First, if the Emacs you are using is not responding to commands, type
        !          11378: @kbd{C-g C-g} to get out of it and then start a new one.
        !          11379: 
        !          11380: @findex doctor
        !          11381:   Second, type @kbd{M-x doctor @key{RET}}.
        !          11382: 
        !          11383:   The doctor will make you feel better.  Each time you say something to
        !          11384: the doctor, you must end it by typing @key{RET} @key{RET}.  This lets the
        !          11385: doctor know you are finished.
        !          11386: 
        !          11387: @node Bugs, Manifesto, Lossage, Top
        !          11388: @section Reporting Bugs
        !          11389: 
        !          11390: @cindex bugs
        !          11391:   Sometimes you will encounter a bug in Emacs.  Although we cannot promise
        !          11392: we can or will fix the bug, and we might not even agree that it is a bug,
        !          11393: we want to hear about bugs you encounter in case we do want to fix them.
        !          11394: 
        !          11395:   To make it possible for us to fix a bug, you must report it.  In order
        !          11396: to do so effectively, you must know when and how to do it.
        !          11397: 
        !          11398: @subsection When Is There a Bug
        !          11399: 
        !          11400:   If Emacs executes an illegal instruction, or dies with an operating
        !          11401: system error message that indicates a problem in the program (as opposed to
        !          11402: something like ``disk full''), then it is certainly a bug.
        !          11403: 
        !          11404:   If Emacs updates the display in a way that does not correspond to what is
        !          11405: in the buffer, then it is certainly a bug.  If a command seems to do the
        !          11406: wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
        !          11407: case of incorrect display updating.
        !          11408: 
        !          11409:   Taking forever to complete a command can be a bug, but you must make
        !          11410: certain that it was really Emacs's fault.  Some commands simply take a long
        !          11411: time.  Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
        !          11412: received was what you intended to type; if the input was such that you
        !          11413: @var{know} it should have been processed quickly, report a bug.  If you
        !          11414: don't know whether the command should take a long time, find out by looking
        !          11415: in the manual or by asking for assistance.
        !          11416: 
        !          11417:   If a command you are familiar with causes an Emacs error message in a
        !          11418: case where its usual definition ought to be reasonable, it is probably a
        !          11419: bug.
        !          11420: 
        !          11421:   If a command does the wrong thing, that is a bug.  But be sure you know
        !          11422: for certain what it ought to have done.  If you aren't familiar with the
        !          11423: command, or don't know for certain how the command is supposed to work,
        !          11424: then it might actually be working right.  Rather than jumping to
        !          11425: conclusions, show the problem to someone who knows for certain.
        !          11426: 
        !          11427:   Finally, a command's intended definition may not be best for editing
        !          11428: with.  This is a very important sort of problem, but it is also a matter of
        !          11429: judgment.  Also, it is easy to come to such a conclusion out of ignorance
        !          11430: of some of the existing features.  It is probably best not to complain
        !          11431: about such a problem until you have checked the documentation in the usual
        !          11432: ways, feel confident that you understand it, and know for certain that what
        !          11433: you want is not available.  If you are not sure what the command is
        !          11434: supposed to do after a careful reading of the manual, check the index and
        !          11435: glossary for any terms that may be unclear.  If you still do not
        !          11436: understand, this indicates a bug in the manual.  The manual's job is to
        !          11437: make everything clear.  It is just as important to report documentation
        !          11438: bugs as program bugs.
        !          11439: 
        !          11440:   If the on-line documentation string of a function or variable disagrees
        !          11441: with the manual, one of them must be wrong, so report the bug.
        !          11442: 
        !          11443: @subsection How to Report a Bug
        !          11444: 
        !          11445: @findex emacs-version
        !          11446:   When you decide that there is a bug, it is important to report it and to
        !          11447: report it in a way which is useful.  What is most useful is an exact
        !          11448: description of what commands you type, starting with the shell command to
        !          11449: run Emacs, until the problem happens.  Always include the version number
        !          11450: of Emacs that you are using; type @kbd{M-x emacs-version} to print this.
        !          11451: 
        !          11452:   The most important principle in reporting a bug is to report @var{facts},
        !          11453: not hypotheses or categorizations.  It is always easier to report the facts,
        !          11454: but people seem to prefer to strain to posit explanations and report
        !          11455: them instead.  If the explanations are based on guesses about how Emacs is
        !          11456: implemented, they will be useless; we will have to try to figure out what
        !          11457: the facts must have been to lead to such speculations.  Sometimes this is
        !          11458: impossible.  But in any case, it is unnecessary work for us.
        !          11459: 
        !          11460:   For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
        !          11461: @key{RET}}, visiting a file which (you know) happens to be rather large,
        !          11462: and Emacs prints out @samp{I feel pretty today}.  The best way to report
        !          11463: the bug is with a sentence like the preceding one, because it gives all the
        !          11464: facts and nothing but the facts.
        !          11465: 
        !          11466:   Do not assume that the problem is due to the size of the file and say,
        !          11467: ``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
        !          11468: This is what we mean by ``guessing explanations''.  The problem is just as
        !          11469: likely to be due to the fact that there is a @code{z} in the file name.  If
        !          11470: this is so, then when we got your report, we would try out the problem with
        !          11471: some ``large file'', probably with no @code{z} in its name, and not find
        !          11472: anything wrong.  There is no way in the world that we could guess that we
        !          11473: should try visiting a file with a @code{z} in its name.
        !          11474: 
        !          11475:   Alternatively, the problem might be due to the fact that the file starts
        !          11476: with exactly 25 spaces.  For this reason, you should make sure that you
        !          11477: inform us of the exact contents of any file that is needed to reproduce the
        !          11478: bug.  What if the problem only occurs when you have typed the @kbd{C-x C-a}
        !          11479: command previously?  This is why we ask you to give the exact sequence of
        !          11480: characters you typed since starting to use Emacs.
        !          11481: 
        !          11482:   You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
        !          11483: you @i{know} that it makes no difference which visiting command is used.
        !          11484: Similarly, rather than saying ``if I have three characters on the line,''
        !          11485: say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is
        !          11486: the way you entered the text.@refill
        !          11487: 
        !          11488:   If you are not in Fundamental mode when the problem occurs, you should
        !          11489: say what mode you are in.
        !          11490: 
        !          11491:   If the manifestation of the bug is an Emacs error message, it is
        !          11492: important to report not just the text of the error message but a backtrace
        !          11493: showing how the Lisp program in Emacs arrived at the error.  To make the
        !          11494: backtrace, you must execute the Lisp expression @code{(setq debug-on-error@ t)}
        !          11495: before the error happens (that is to say, you must execute that expression
        !          11496: and then make the bug happen).  This causes the Lisp debugger to run
        !          11497: (@pxref{Lisp Debug}).  The debugger's backtrace can be copied as text into
        !          11498: the bug report.  This use of the debugger is possible only if you know how
        !          11499: to make the bug happen again.  Do note the error message the first time the
        !          11500: bug happens, so if you can't make it happen again, you can report at least
        !          11501: that.
        !          11502: 
        !          11503:   Check whether any programs you have loaded into the Lisp world, including
        !          11504: your @file{.emacs} file, set any variables that may affect the functioning
        !          11505: of Emacs.  Also, see whether the problem happens in a freshly started Emacs
        !          11506: without loading your @file{.emacs} file (start Emacs with the @code{-q} switch
        !          11507: to prevent loading the init file.)  If the problem does @var{not} occur
        !          11508: then, it is essential that we know the contents of any programs that you
        !          11509: must load into the Lisp world in order to cause the problem to occur.
        !          11510: 
        !          11511:   If the problem does depend on an init file or other Lisp programs that
        !          11512: are not part of the standard Emacs system, then you should make sure it is
        !          11513: not a bug in those programs by complaining to their maintainers, first.
        !          11514: After they verify that they are using Emacs in a way that is supposed to
        !          11515: work, they should report the bug.
        !          11516: 
        !          11517:   If you can tell us a way to cause the problem without visiting any files,
        !          11518: please do so.  This makes it much easier to debug.  If you do need files,
        !          11519: make sure you arrange for us to see their exact contents.  For example, it
        !          11520: can often matter whether there are spaces at the ends of lines, or a
        !          11521: newline after the last line in the buffer (nothing ought to care whether
        !          11522: the last line is terminated, but tell that to the bugs).
        !          11523: 
        !          11524: @findex open-dribble-file
        !          11525: @cindex dribble file
        !          11526:   The easy way to record the input to Emacs precisely is to to write a
        !          11527: dribble file; execute the Lisp expression
        !          11528: 
        !          11529: @example
        !          11530: (open-dribble-file "~/dribble")
        !          11531: @end example
        !          11532: 
        !          11533: @noindent
        !          11534: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
        !          11535: Emacs.  From then on, all Emacs input will be written in the specified
        !          11536: dribble file until the Emacs process is killed.
        !          11537: 
        !          11538: @findex open-termscript
        !          11539: @cindex termcript file
        !          11540:   For possible display bugs, it is important to report the terminal type
        !          11541: (the value of environment variable @code{TERM}), the termcap entry for the
        !          11542: terminal (since @file{/etc/termcap} is not identical on all machines), and
        !          11543: the output that Emacs actually sent to the terminal.  The way to collect
        !          11544: this output is to execute the Lisp expression
        !          11545: 
        !          11546: @example
        !          11547: (open-termscript "~/termscript")
        !          11548: @end example
        !          11549: 
        !          11550: @noindent
        !          11551: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just
        !          11552: after starting Emacs.  From then on, all output from Emacs to the terminal
        !          11553: will be written in the specified termscript file as well, until the Emacs
        !          11554: process is killed.  If the problem happens when Emacs starts up, put this
        !          11555: expression into your @file{~/.emacs} file so that the termscript file will
        !          11556: be open when Emacs displays the screen for the first time.  Be warned:
        !          11557: it is often difficult, and sometimes impossible, to fix a terminal-dependent
        !          11558: bug without access to a terminal of the type that stimulates the bug.@refill
        !          11559: 
        !          11560:   The address for reporting bugs is
        !          11561: 
        !          11562: @format
        !          11563: GNU Emacs Bugs
        !          11564: 545 Tech Sq, rm 703
        !          11565: Cambridge, MA 02139
        !          11566: @end format
        !          11567: 
        !          11568: @noindent
        !          11569: or, on Usenet, mail to @samp{mit-eddie!bug-gnu-emacs}.
        !          11570: 
        !          11571:   Once again, we do not promise to fix the bug; but if the bug is serious,
        !          11572: or ugly, or easy to fix, chances are we will want to.
        !          11573: 
        !          11574: @node Manifesto,, Bugs, Top
        !          11575: @unnumbered The GNU Manifesto
        !          11576: 
        !          11577: @unnumberedsec What's GNU?  Gnu's Not Unix!
        !          11578: 
        !          11579: GNU, which stands for Gnu's Not Unix, is the name for the complete
        !          11580: Unix-compatible software system which I am writing so that I can give it
        !          11581: away free to everyone who can use it.  Several other volunteers are helping
        !          11582: me.  Contributions of time, money, programs and equipment are greatly
        !          11583: needed.
        !          11584: 
        !          11585: So far we have a portable C and Pascal compiler which compiles for Vax and
        !          11586: 68000 (though needing much rewriting), an Emacs-like text editor with Lisp
        !          11587: for writing editor commands, a yacc-compatible parser generator, a linker,
        !          11588: and around 35 utilities.  A shell (command interpreter) is nearly
        !          11589: completed.  When the kernel and a debugger are written, it will be possible
        !          11590: to distribute a GNU system suitable for program development.  After this we
        !          11591: will add a text formatter, an Empire game, a spreadsheet, and hundreds of
        !          11592: other things, plus on-line documentation.  We hope to supply, eventually,
        !          11593: everything useful that normally comes with a Unix system, and more.
        !          11594: 
        !          11595: GNU will be able to run Unix programs, but will not be identical to Unix.
        !          11596: We will make all improvements that are convenient, based on our experience
        !          11597: with other operating systems.  In particular, we plan to have longer
        !          11598: filenames, file version numbers, a crashproof file system, filename
        !          11599: completion perhaps, terminal-independent display support, and eventually a
        !          11600: Lisp-based window system through which several Lisp programs and ordinary
        !          11601: Unix programs can share a screen.  Both C and Lisp will be available as
        !          11602: system programming languages.  We will try to support UUCP, MIT Chaosnet,
        !          11603: and Internet protocols for communication.
        !          11604: 
        !          11605: GNU is aimed initially at machines in the 68000/16000 class, with virtual
        !          11606: memory, because they are the easiest machines to make it run on.  The extra
        !          11607: effort to make it run on smaller machines will be left to someone who wants
        !          11608: to use it on them.
        !          11609: 
        !          11610: To avoid horrible confusion, please pronounce the `G' in the word `GNU'
        !          11611: when it is the name of this project.
        !          11612: 
        !          11613: @unnumberedsec Why I Must Write GNU
        !          11614: 
        !          11615: I consider that the golden rule requires that if I like a program I must
        !          11616: share it with other people who like it.  Software sellers want to divide
        !          11617: the users and conquer them, making each user agree not to share with
        !          11618: others.  I refuse to break solidarity with other users in this way.  I
        !          11619: cannot in good conscience sign a nondisclosure agreement or a software
        !          11620: license agreement.  For years I worked within the Artificial Intelligence
        !          11621: Lab to resist such tendencies and other inhospitalities, but eventually
        !          11622: they had gone too far: I could not remain in an institution where such
        !          11623: things are done for me against my will.
        !          11624: 
        !          11625: So that I can continue to use computers without dishonor, I have decided to
        !          11626: put together a sufficient body of free software so that I will be able to
        !          11627: get along without any software that is not free.  I have resigned from the
        !          11628: AI lab to deny MIT any legal excuse to prevent me from giving GNU away.
        !          11629: 
        !          11630: @unnumberedsec Why GNU Will Be Compatible with Unix
        !          11631: 
        !          11632: Unix is not my ideal system, but it is not too bad.  The essential features
        !          11633: of Unix seem to be good ones, and I think I can fill in what Unix lacks
        !          11634: without spoiling them.  And a system compatible with Unix would be
        !          11635: convenient for many other people to adopt.
        !          11636: 
        !          11637: @unnumberedsec How GNU Will Be Available
        !          11638: 
        !          11639: GNU is not in the public domain.  Everyone will be permitted to modify and
        !          11640: redistribute GNU, but no distributor will be allowed to restrict its
        !          11641: further redistribution.  That is to say, proprietary modifications will not
        !          11642: be allowed.  I want to make sure that all versions of GNU remain free.
        !          11643: 
        !          11644: @unnumberedsec Why Many Other Programmers Want to Help
        !          11645: 
        !          11646: I have found many other programmers who are excited about GNU and want to
        !          11647: help.
        !          11648: 
        !          11649: Many programmers are unhappy about the commercialization of system
        !          11650: software.  It may enable them to make more money, but it requires them to
        !          11651: feel in conflict with other programmers in general rather than feel as
        !          11652: comrades.  The fundamental act of friendship among programmers is the
        !          11653: sharing of programs; marketing arrangements now typically used essentially
        !          11654: forbid programmers to treat others as friends.  The purchaser of software
        !          11655: must choose between friendship and obeying the law.  Naturally, many decide
        !          11656: that friendship is more important.  But those who believe in law often do
        !          11657: not feel at ease with either choice.  They become cynical and think that
        !          11658: programming is just a way of making money.
        !          11659: 
        !          11660: By working on and using GNU rather than proprietary programs, we can be
        !          11661: hospitable to everyone and obey the law.  In addition, GNU serves as an
        !          11662: example to inspire and a banner to rally others to join us in sharing.
        !          11663: This can give us a feeling of harmony which is impossible if we use
        !          11664: software that is not free.  For about half the programmers I talk to, this
        !          11665: is an important happiness that money cannot replace.
        !          11666: 
        !          11667: @unnumberedsec How You Can Contribute
        !          11668: 
        !          11669: I am asking computer manufacturers for donations of machines and money.
        !          11670: I'm asking individuals for donations of programs and work.
        !          11671: 
        !          11672: One consequence you can expect if you donate machines is that GNU will run
        !          11673: on them at an early date.  The machines should be complete, ready to use
        !          11674: systems, approved for use in a residential area, and not in need of
        !          11675: sophisticated cooling or power.
        !          11676: 
        !          11677: I have found very many programmers eager to contribute part-time work for
        !          11678: GNU.  For most projects, such part-time distributed work would be very hard
        !          11679: to coordinate; the independently-written parts would not work together.
        !          11680: But for the particular task of replacing Unix, this problem is absent.  A
        !          11681: complete Unix system contains hundreds of utility programs, each of which
        !          11682: is documented separately.  Most interface specifications are fixed by Unix
        !          11683: compatibility.  If each contributor can write a compatible replacement for
        !          11684: a single Unix utility, and make it work properly in place of the original
        !          11685: on a Unix system, then these utilities will work right when put together.
        !          11686: Even allowing for Murphy to create a few unexpected problems, assembling
        !          11687: these components will be a feasible task.  (The kernel will require closer
        !          11688: communication and will be worked on by a small, tight group.)
        !          11689: 
        !          11690: If I get donations of money, I may be able to hire a few people full or
        !          11691: part time.  The salary won't be high by programmers' standards, but I'm
        !          11692: looking for people for whom building community spirit is as important as
        !          11693: making money.  I view this as a way of enabling dedicated people to devote
        !          11694: their full energies to working on GNU by sparing them the need to make a
        !          11695: living in another way.
        !          11696: 
        !          11697: @unnumberedsec Why All Computer Users Will Benefit
        !          11698: 
        !          11699: Once GNU is written, everyone will be able to obtain good system software
        !          11700: free, just like air.
        !          11701: 
        !          11702: This means much more than just saving everyone the price of a Unix license.
        !          11703: It means that much wasteful duplication of system programming effort will
        !          11704: be avoided.  This effort can go instead into advancing the state of the
        !          11705: art.
        !          11706: 
        !          11707: Complete system sources will be available to everyone.  As a result, a user
        !          11708: who needs changes in the system will always be free to make them himself,
        !          11709: or hire any available programmer or company to make them for him.  Users
        !          11710: will no longer be at the mercy of one programmer or company which owns the
        !          11711: sources and is in sole position to make changes.
        !          11712: 
        !          11713: Schools will be able to provide a much more educational environment by
        !          11714: encouraging all students to study and improve the system code.  Harvard's
        !          11715: computer lab used to have the policy that no program could be installed on
        !          11716: the system if its sources were not on public display, and upheld it by
        !          11717: actually refusing to install certain programs.  I was very much inspired by
        !          11718: this.
        !          11719: 
        !          11720: Finally, the overhead of considering who owns the system software and what
        !          11721: one is or is not entitled to do with it will be lifted.
        !          11722: 
        !          11723: Arrangements to make people pay for using a program, including licensing of
        !          11724: copies, always incur a tremendous cost to society through the cumbersome
        !          11725: mechanisms necessary to figure out how much (that is, which programs) a
        !          11726: person must pay for.  And only a police state can force everyone to obey
        !          11727: them.  Consider a space station where air must be manufactured at great
        !          11728: cost: charging each breather per liter of air may be fair, but wearing the
        !          11729: metered gas mask all day and all night is intolerable even if everyone can
        !          11730: afford to pay the air bill.  And the TV cameras everywhere to see if you
        !          11731: ever take the mask off are outrageous.  It's better to support the air
        !          11732: plant with a head tax and chuck the masks.
        !          11733: 
        !          11734: Copying all or parts of a program is as natural to a programmer as
        !          11735: breathing, and as productive.  It ought to be as free.
        !          11736: 
        !          11737: @unnumberedsec Some Easily Rebutted Objections to GNU's Goals
        !          11738: 
        !          11739: @quotation
        !          11740: ``Nobody will use it if it is free, because that means they can't rely
        !          11741: on any support.''
        !          11742: 
        !          11743: ``You have to charge for the program to pay for providing the
        !          11744: support.''
        !          11745: @end quotation
        !          11746: 
        !          11747: If people would rather pay for GNU plus service than get GNU free without
        !          11748: service, a company to provide just service to people who have obtained GNU
        !          11749: free ought to be profitable.
        !          11750: 
        !          11751: We must distinguish between support in the form of real programming work
        !          11752: and mere handholding.  The former is something one cannot rely on from a
        !          11753: software vendor.  If your problem is not shared by enough people, the
        !          11754: vendor will tell you to get lost.
        !          11755: 
        !          11756: If your business needs to be able to rely on support, the only way is to
        !          11757: have all the necessary sources and tools.  Then you can hire any available
        !          11758: person to fix your problem; you are not at the mercy of any individual.
        !          11759: With Unix, the price of sources puts this out of consideration for most
        !          11760: businesses.  With GNU this will be easy.  It is still possible for there to
        !          11761: be no available competent person, but this problem cannot be blamed on
        !          11762: distibution arrangements.  GNU does not eliminate all the world's problems,
        !          11763: only some of them.
        !          11764: 
        !          11765: Meanwhile, the users who know nothing about computers need handholding:
        !          11766: doing things for them which they could easily do themselves but don't know
        !          11767: how.
        !          11768: 
        !          11769: Such services could be provided by companies that sell just hand-holding
        !          11770: and repair service.  If it is true that users would rather spend money and
        !          11771: get a product with service, they will also be willing to buy the service
        !          11772: having got the product free.  The service companies will compete in quality
        !          11773: and price; users will not be tied to any particular one.  Meanwhile, those
        !          11774: of us who don't need the service should be able to use the program without
        !          11775: paying for the service.
        !          11776: 
        !          11777: @quotation
        !          11778: ``You cannot reach many people without advertising,
        !          11779: and you must charge for the program to support that.''
        !          11780: 
        !          11781: ``It's no use advertising a program people can get free.''
        !          11782: @end quotation
        !          11783: 
        !          11784: There are various forms of free or very cheap publicity that can be used to
        !          11785: inform numbers of computer users about something like GNU.  But it may be
        !          11786: true that one can reach more microcomputer users with advertising.  If this
        !          11787: is really so, a business which advertises the service of copying and
        !          11788: mailing GNU for a fee ought to be successful enough to pay for its
        !          11789: advertising and more.  This way, only the users who benefit from the
        !          11790: advertising pay for it.
        !          11791: 
        !          11792: On the other hand, if many people get GNU from their friends, and such
        !          11793: companies don't succeed, this will show that advertising was not really
        !          11794: necessary to spread GNU.  Why is it that free market advocates don't want
        !          11795: to let the free market decide this?
        !          11796: 
        !          11797: @quotation
        !          11798: ``My company needs a proprietary operating system
        !          11799: to get a competitive edge.''
        !          11800: @end quotation
        !          11801: 
        !          11802: GNU will remove operating system software from the realm of competition.
        !          11803: You will not be able to get an edge in this area, but neither will your
        !          11804: competitors be able to get an edge over you.  You and they will compete in
        !          11805: other areas, while benefitting mutually in this one.  If your business is
        !          11806: selling an operating system, you will not like GNU, but that's tough on
        !          11807: you.  If your business is something else, GNU can save you from being
        !          11808: pushed into the expensive business of selling operating systems.
        !          11809: 
        !          11810: I would like to see GNU development supported by gifts from many
        !          11811: manufacturers and users, reducing the cost to each.
        !          11812: 
        !          11813: @quotation
        !          11814: ``Don't programmers deserve a reward for their creativity?''
        !          11815: @end quotation
        !          11816: 
        !          11817: If anything deserves a reward, it is social contribution.  Creativity can
        !          11818: be a social contribution, but only in so far as society is free to use the
        !          11819: results.  If programmers deserve to be rewarded for creating innovative
        !          11820: programs, by the same token they deserve to be punished if they restrict
        !          11821: the use of these programs.
        !          11822: 
        !          11823: @quotation
        !          11824: ``Shouldn't a programmer be able to ask for a reward for his creativity?''
        !          11825: @end quotation
        !          11826: 
        !          11827: There is nothing wrong with wanting pay for work, or seeking to maximize
        !          11828: one's income, as long as one does not use means that are destructive.  But
        !          11829: the means customary in the field of software today are based on
        !          11830: destruction.
        !          11831: 
        !          11832: Extracting money from users of a program by restricting their use of it is
        !          11833: destructive because the restrictions reduce the amount and the ways that
        !          11834: the program can be used.  This reduces the amount of wealth that humanity
        !          11835: derives from the program.  When there is a deliberate choice to restrict,
        !          11836: the harmful consequences are deliberate destruction.
        !          11837: 
        !          11838: The reason a good citizen does not use such destructive means to become
        !          11839: wealthier is that, if everyone did so, we would all become poorer from the
        !          11840: mutual destructiveness.  This is Kantian ethics; or, the Golden Rule.
        !          11841: Since I do not like the consequences that result if everyone hoards
        !          11842: information, I am required to consider it wrong for one to do so.
        !          11843: Specifically, the desire to be rewarded for one's creativity does not
        !          11844: justify depriving the world in general of all or part of that creativity.
        !          11845: 
        !          11846: @quotation
        !          11847: ``Won't programmers starve?''
        !          11848: @end quotation
        !          11849: 
        !          11850: I could answer that nobody is forced to be a programmer.  Most of us cannot
        !          11851: manage to get any money for standing on the street and making faces.  But
        !          11852: we are not, as a result, condemned to spend our lives standing on the
        !          11853: street making faces, and starving.  We do something else.
        !          11854: 
        !          11855: But that is the wrong answer because it accepts the questioner's implicit
        !          11856: assumption: that without ownership of software, programmers cannot possibly
        !          11857: be paid a cent.  Supposedly it is all or nothing.
        !          11858: 
        !          11859: The real reason programmers will not starve is that it will still be
        !          11860: possible for them to get paid for programming; just not paid as much as
        !          11861: now.
        !          11862: 
        !          11863: Restricting copying is not the only basis for business in software.  It is
        !          11864: the most common basis because it brings in the most money.  If it were
        !          11865: prohibited, or rejected by the customer, software business would move to
        !          11866: other bases of organization which are now used less often.  There are
        !          11867: always numerous ways to organize any kind of business.
        !          11868: 
        !          11869: Probably programming will not be as lucrative on the new basis as it is
        !          11870: now.  But that is not an argument against the change.  It is not considered
        !          11871: an injustice that sales clerks make the salaries that they now do.  If
        !          11872: programmers made the same, that would not be an injustice either.  (In
        !          11873: practice they would still make considerably more than that.)
        !          11874: 
        !          11875: @quotation
        !          11876: ``Don't people have a right to control how their creativity is used?''
        !          11877: @end quotation
        !          11878: 
        !          11879: ``Control over the use of one's ideas'' really constitutes control over
        !          11880: other people's lives; and it is usually used to make their lives more
        !          11881: difficult.
        !          11882: 
        !          11883: People who have studied the issue of intellectual property rights carefully
        !          11884: (such as lawyers) say that there is no intrinsic right to intellectual
        !          11885: property.  The kinds of supposed intellectual property rights that the
        !          11886: government recognizes were created by specific acts of legislation for
        !          11887: specific purposes.
        !          11888: 
        !          11889: For example, the patent system was established to encourage inventors to
        !          11890: disclose the details of their inventions.  Its purpose was to help society
        !          11891: rather than to help inventors.  At the time, the life span of 17 years for
        !          11892: a patent was short compared with the rate of advance of the state of the
        !          11893: art.  Since patents are an issue only among manufacturers, for whom the
        !          11894: cost and effort of a license agreement are small compared with setting up
        !          11895: production, the patents often do not do much harm.  They do not obstruct
        !          11896: most individuals who use patented products.
        !          11897: 
        !          11898: The idea of copyright did not exist in ancient times, when authors
        !          11899: frequently copied other authors at length in works of non-fiction.  This
        !          11900: practice was useful, and is the only way many authors' works have survived
        !          11901: even in part.  The copyright system was created expressly for the purpose
        !          11902: of encouraging authorship.  In the domain for which it was
        !          11903: invented---books, which could be copied economically only on a printing
        !          11904: press---it did little harm, and did not obstruct most of the individuals
        !          11905: who read the books.
        !          11906: 
        !          11907: All intellectual property rights are just licenses granted by society
        !          11908: because it was thought, rightly or wrongly, that society as a whole would
        !          11909: benefit by granting them.  But in any particular situation, we have to ask:
        !          11910: are we really better off granting such license?  What kind of act are we
        !          11911: licensing a person to do?
        !          11912: 
        !          11913: The case of programs today is very different from that of books a hundred
        !          11914: years ago.  The fact that the easiest way to copy a program is from one
        !          11915: neighbor to another, the fact that a program has both source code and
        !          11916: object code which are distinct, and the fact that a program is used rather
        !          11917: than read and enjoyed, combine to create a situation in which a person who
        !          11918: enforces a copyright is harming society as a whole both materially and
        !          11919: spiritually; in which a person should not do so regardless of whether the
        !          11920: law enables him to.
        !          11921: 
        !          11922: @quotation
        !          11923: ``Competition makes things get done better.''
        !          11924: @end quotation
        !          11925: 
        !          11926: The paradigm of competition is a race: by rewarding the winner, we
        !          11927: encourage everyone to run faster.  When capitalism really works this way,
        !          11928: it does a good job; but its defenders are wrong in assuming it always works
        !          11929: this way.  If the runners forget why the reward is offered and become
        !          11930: intent on winning, no matter how, they may find other strategies---such as,
        !          11931: attacking other runners.  If the runners get into a fist fight, they will
        !          11932: all finish late.
        !          11933: 
        !          11934: Proprietary and secret software is the moral equivalent of runners in a
        !          11935: fist fight.  Sad to say, the only referee we've got does not seem to
        !          11936: object to fights; he just regulates them (``For every ten yards you run,
        !          11937: you can fire one shot'').  He really ought to break them up, and penalize
        !          11938: runners for even trying to fight.
        !          11939: 
        !          11940: @quotation
        !          11941: ``Won't everyone stop programming without a monetary incentive?''
        !          11942: @end quotation
        !          11943: 
        !          11944: Actually, many people will program with absolutely no monetary incentive.
        !          11945: Programming has an irresistible fascination for some people, usually the
        !          11946: people who are best at it.  There is no shortage of professional musicians
        !          11947: who keep at it even though they have no hope of making a living that way.
        !          11948: 
        !          11949: But really this question, though commonly asked, is not appropriate to the
        !          11950: situation.  Pay for programmers will not disappear, only become less.  So
        !          11951: the right question is, will anyone program with a reduced monetary
        !          11952: incentive?  My experience shows that they will.
        !          11953: 
        !          11954: For more than ten years, many of the world's best programmers worked at the
        !          11955: Artificial Intelligence Lab for far less money than they could have had
        !          11956: anywhere else.  They got many kinds of non-monetary rewards: fame and
        !          11957: appreciation, for example.  And creativity is also fun, a reward in itself.
        !          11958: 
        !          11959: Then most of them left when offered a chance to do the same interesting
        !          11960: work for a lot of money.
        !          11961: 
        !          11962: What the facts show is that people will program for reasons other than
        !          11963: riches; but if given a chance to make a lot of money as well, they will
        !          11964: come to expect and demand it.  Low-paying organizations do poorly in
        !          11965: competition with high-paying ones, but they do not have to do badly if the
        !          11966: high-paying ones are banned.
        !          11967: 
        !          11968: @quotation
        !          11969: ``We need the programmers desperately.  If they demand that we
        !          11970: stop helping our neighbors, we have to obey.''
        !          11971: @end quotation
        !          11972: 
        !          11973: You're never so desperate that you have to obey this sort of demand.
        !          11974: Remember: millions for defense, but not a cent for tribute!
        !          11975: 
        !          11976: @quotation
        !          11977: ``Programmers need to make a living somehow.''
        !          11978: @end quotation
        !          11979: 
        !          11980: In the short run, this is true.  However, there are plenty of ways that
        !          11981: programmers could make a living without selling the right to use a program.
        !          11982: This way is customary now because it brings programmers and businessmen the
        !          11983: most money, not because it is the only way to make a living.  It is easy to
        !          11984: find other ways if you want to find them.  Here are a number of examples.
        !          11985: 
        !          11986: A manufacturer introducing a new computer will pay for the porting of
        !          11987: operating systems onto the new hardware.
        !          11988: 
        !          11989: The sale of teaching, hand-holding and maintenance services could also
        !          11990: employ programmers.
        !          11991: 
        !          11992: People with new ideas could distribute programs as freeware, asking for
        !          11993: donations from satisfied users, or selling hand-holding services.  I have
        !          11994: met people who are already working this way successfully.
        !          11995: 
        !          11996: Users with related needs can form users' groups, and pay dues.  A group
        !          11997: would contract with programming companies to write programs that the
        !          11998: group's members would like to use.
        !          11999: 
        !          12000: All sorts of development can be funded with a Software Tax:
        !          12001: 
        !          12002: @quotation
        !          12003: Suppose everyone who buys a computer has to pay x percent of
        !          12004: the price as a software tax.  The government gives this to
        !          12005: an agency like the NSF to spend on software development.
        !          12006: 
        !          12007: But if the computer buyer makes a donation to software development
        !          12008: himself, he can take a credit against the tax.  He can donate to
        !          12009: the project of his own choosing---often, chosen because he hopes to
        !          12010: use the results when it is done.  He can take a credit for any amount
        !          12011: of donation up to the total tax he had to pay.
        !          12012: 
        !          12013: The total tax rate could be decided by a vote of the payers of
        !          12014: the tax, weighted according to the amount they will be taxed on.
        !          12015: 
        !          12016: The consequences:
        !          12017: 
        !          12018: @itemize @bullet
        !          12019: @item
        !          12020: The computer-using community supports software development.
        !          12021: @item
        !          12022: This community decides what level of support is needed.
        !          12023: @item
        !          12024: Users who care which projects their share is spent on
        !          12025: can choose this for themselves.
        !          12026: @end itemize
        !          12027: @end quotation
        !          12028: 
        !          12029: In the long run, making programs free is a step toward the post-scarcity
        !          12030: world, where nobody will have to work very hard just to make a living.
        !          12031: People will be free to devote themselves to activities that are fun, such
        !          12032: as programming, after spending the necessary ten hours a week on required
        !          12033: tasks such as legislation, family counseling, robot repair and asteroid
        !          12034: prospecting.  There will be no need to be able to make a living from
        !          12035: programming.
        !          12036: 
        !          12037: We have already greatly reduced the amount of work that the whole society
        !          12038: must do for its actual productivity, but only a little of this has
        !          12039: translated itself into leisure for workers because much nonproductive
        !          12040: activity is required to accompany productive activity.  The main causes of
        !          12041: this are bureaucracy and isometric struggles against competition.  Free
        !          12042: software will greatly reduce these drains in the area of software
        !          12043: production.  We must do this, in order for technical gains in productivity
        !          12044: to translate into less work for us.
        !          12045: 
        !          12046: @node Glossary, Key Index, Intro, Top
        !          12047: @unnumbered Glossary
        !          12048: 
        !          12049: @table @asis
        !          12050: @item Abbrev
        !          12051: An abbrev is a text string which expands into a different text string
        !          12052: when present in the buffer.  For example, you might define a short
        !          12053: word as an abbrev for a long phrase that you want to insert
        !          12054: frequently.  @xref{Abbrevs}.
        !          12055: 
        !          12056: @item Aborting
        !          12057: Aborting means getting out of a recursive edit (q.v.@:).  The
        !          12058: commands @kbd{C-]} and @kbd{M-x top-level} are used for this.
        !          12059: @xref{Quitting}.
        !          12060: 
        !          12061: @item Auto Fill mode
        !          12062: Auto Fill mode is a minor mode in which text that you insert is
        !          12063: automatically broken into lines of fixed width.  @xref{Filling}.
        !          12064: 
        !          12065: @item Balance Parentheses
        !          12066: Emacs can balance parentheses manually or automatically.  Manual
        !          12067: balancing is done by the commands to move over balanced expressions
        !          12068: (@pxref{Lists}).  Automatic balancing is done by blinking the
        !          12069: parenthesis that matches one just inserted (@pxref{Matching,,Matching
        !          12070: Parens}).
        !          12071: 
        !          12072: @item Bind
        !          12073: To bind a key is to change its binding (q.v.@:).  @xref{Rebinding}.
        !          12074: 
        !          12075: @item Binding
        !          12076: A key gets its meaning in Emacs by having a binding which is a
        !          12077: command (q.v.@:), a Lisp function that is run when the key is typed.
        !          12078: @xref{Commands,Binding}.  Customization often involves rebinding a
        !          12079: character to a different command function.  The bindings of all keys
        !          12080: are recorded in the keymaps (q.v.@:).  @xref{Keymaps}.
        !          12081: 
        !          12082: @item Blank Lines
        !          12083: Blank lines are lines that contain only whitespace.  Emacs has several
        !          12084: commands for operating on the blank lines in the buffer.
        !          12085: 
        !          12086: @item Buffer
        !          12087: The buffer is the basic editing unit; one buffer corresponds to one
        !          12088: piece of text being edited.  You can have several buffers, but at any
        !          12089: time you are editing only one, the `selected' buffer, though several
        !          12090: can be visible when you are using multiple windows.  @xref{Buffers}.
        !          12091: 
        !          12092: @item Buffer Selection History
        !          12093: Emacs keeps a buffer selection history which records how recently each
        !          12094: Emacs buffer has been selected.  This is used for choosing a buffer to
        !          12095: select.  @xref{Buffers}.
        !          12096: 
        !          12097: @item C-
        !          12098: @samp{C} in the name of a character is an abbreviation for Control.
        !          12099: @xref{Characters,C-}.
        !          12100: 
        !          12101: @item C-M-
        !          12102: @samp{C-M-} in the name of a character is an abbreviation for
        !          12103: Control-Meta.  @xref{Characters,C-M-}.
        !          12104: 
        !          12105: @item Case Conversion
        !          12106: Case conversion means changing text from upper case to lower case or
        !          12107: vice versa.  @xref{Case}, for the commands for case conversion.
        !          12108: 
        !          12109: @item Characters
        !          12110: Characters form the contents of an Emacs buffer; also, Emacs commands
        !          12111: are invoked by keys (q.v.@:), which are sequences of one or more
        !          12112: characters.  @xref{Characters}.
        !          12113: 
        !          12114: @item Command
        !          12115: A command is a Lisp function specially defined to be able to serve as
        !          12116: a key binding in Emacs.  When you type a key (q.v.@:), its binding
        !          12117: (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find the
        !          12118: command to run.  @xref{Commands}.
        !          12119: 
        !          12120: @item Command Name
        !          12121: A command name is the name of a Lisp symbol which is a command
        !          12122: (@pxref{Commands}).  You can invoke any command by its name using
        !          12123: @kbd{M-x} (@pxref{M-x}).
        !          12124: 
        !          12125: @item Comments
        !          12126: A comment is text in a program which is intended only for humans
        !          12127: reading the program, and is marked specially so that it will be
        !          12128: ignored when the program is loaded or compiled.  Emacs offers special
        !          12129: commands for creating, aligning and killing comments.
        !          12130: @xref{Comments}.
        !          12131: 
        !          12132: @item Compilation
        !          12133: Compilation is the process of creating an executable program from
        !          12134: source code.  Emacs has commands for compiling files of Emacs Lisp
        !          12135: code (@pxref{Lisp Libraries}) and programs in C and other languages
        !          12136: (@pxref{Compilation}).
        !          12137: 
        !          12138: @item Completion
        !          12139: Completion is what Emacs does when it automatically fills out an
        !          12140: abbreviation for a name into the entire name.  Completion is done for
        !          12141: minibuffer (q.v.@:) arguments, when the set of possible valid inputs
        !          12142: is known; for example, on command names, buffer names, and
        !          12143: file names.  Completion occurs when @key{TAB}, @key{SPC} or @key{RET}
        !          12144: is typed.  @xref{Completion}.@refill
        !          12145: 
        !          12146: @item Continuation Line
        !          12147: When a line of text is longer than the width of the screen, it
        !          12148: takes up more than one screen line when displayed.  We say that the
        !          12149: text line is continued, and all screen lines used for it after the
        !          12150: first are called continuation lines.  @xref{Basic,Continuation,Basic
        !          12151: Editing}.
        !          12152: 
        !          12153: @item Control-Character
        !          12154: ASCII characters with octal codes 0 through 040, and also code 0177,
        !          12155: do not have graphic images assigned to them.  These are the control
        !          12156: characters.  Any control character can be typed by holding down the
        !          12157: @key{CTRL} key and typing some other character; some have special keys
        !          12158: on the keyboard.  @key{RET}, @key{TAB}, @key{ESC}, @key{LFD} and
        !          12159: @key{DEL} are all control characters.  @xref{Characters}.@refill
        !          12160: 
        !          12161: @item Current Buffer
        !          12162: The current buffer in Emacs is the Emacs buffer on which most editing
        !          12163: commands operate.  You can select any Emacs buffer as the current one.
        !          12164: @xref{Buffers}.
        !          12165: 
        !          12166: @item Current Line
        !          12167: The line point is on (@pxref{Point}).
        !          12168: 
        !          12169: @item Current Paragraph
        !          12170: The paragraph that point is in.  If point is between paragraphs, the
        !          12171: current paragraph is the one that follows point.  @xref{Paragraphs}.
        !          12172: 
        !          12173: @item Current Defun
        !          12174: The defun (q.v.@:) that point is in.  If point is between defuns, the
        !          12175: current defun is the one that follows point.  @xref{Defuns}.
        !          12176: 
        !          12177: @item Cursor
        !          12178: The cursor is the rectangle on the screen which indicates the position
        !          12179: called point (q.v.@:) at which insertion and deletion takes place.
        !          12180: Often people speak of `the cursor' when, strictly speaking, they mean
        !          12181: `point'.  @xref{Basic,Cursor,Basic Editing}.
        !          12182: 
        !          12183: @item Customization
        !          12184: Customization is making minor changes in the way Emacs works.  It is
        !          12185: often done by setting variables (@pxref{Variables}) or by rebinding
        !          12186: keys (@pxref{Keymaps}).
        !          12187: 
        !          12188: @item Default Argument
        !          12189: The default for an argument is the value that will be assumed if you
        !          12190: do not specify one.  When the minibuffer is used to read an argument,
        !          12191: the default argument is used if you just type @key{RET}.
        !          12192: @xref{Minibuffer}.
        !          12193: 
        !          12194: @item Default Directory
        !          12195: When you specify a file name that does not start with @samp{/} or @samp{~},
        !          12196: it is interpreted relative to the current buffer's default directory.
        !          12197: @xref{Minibuffer File,Default Directory}.
        !          12198: 
        !          12199: @item Defun
        !          12200: A defun is a list at the top level of parenthesis or bracket structure
        !          12201: in a program.  It is so named because most such lists in Lisp programs
        !          12202: are calls to the Lisp function @code{defun}.  @xref{Defuns}.
        !          12203: 
        !          12204: @item @key{DEL}
        !          12205: @key{DEL} is a character that runs the command to delete one character of
        !          12206: text.  @xref{Basic,DEL,Basic Editing}.
        !          12207: 
        !          12208: @item Deletion
        !          12209: Deletion means erasing text without saving it.  Emacs deletes text
        !          12210: only when it is expected not to be worth saving (all whitespace, or
        !          12211: only one character).  The alternative is killing (q.v.@:).
        !          12212: @xref{Killing,Deletion}.
        !          12213: 
        !          12214: @item Deletion of Files
        !          12215: Deleting a file means erasing it from the file system.  @xref{Misc
        !          12216: File Ops}.
        !          12217: 
        !          12218: @item Deletion of Messages
        !          12219: Deleting a message means flagging it to be eliminated from your mail
        !          12220: file.  This can be undone by undeletion until the mail file is expunged.
        !          12221: @xref{Rmail Deletion}.
        !          12222: 
        !          12223: @item Deletion of Windows
        !          12224: Deleting a window means eliminating it from the screen.  Other windows
        !          12225: expand to use up the space.  The deleted window can never come back,
        !          12226: but no actual text is thereby lost.  @xref{Windows}.
        !          12227: 
        !          12228: @item Directory
        !          12229: Files in the Unix file system are grouped into file directories.
        !          12230: @xref{ListDir,,Directories}.
        !          12231: 
        !          12232: @item Dired
        !          12233: Dired is the Emacs facility that displays the contents of a file
        !          12234: directory and allows you to ``edit the directory'', performing
        !          12235: operations on the files in the directory.  @xref{Dired}.
        !          12236: 
        !          12237: @item Disabled Command
        !          12238: A disabled command is one that you may not run without special
        !          12239: confirmation.  The usual reason for disabling a command is that it is
        !          12240: confusing for beginning users.  @xref{Disabling}.
        !          12241: 
        !          12242: @item Dribble File
        !          12243: A file into which Emacs writes all the characters that the user types
        !          12244: on the keyboard.  Dribble files are used to make a record for
        !          12245: debugging Emacs bugs.  Emacs does not make a dribble file unless you
        !          12246: tell it to.  @xref{Bugs}.
        !          12247: 
        !          12248: @item Echo Area
        !          12249: The echo area is the bottom line of the screen, used for echoing the
        !          12250: arguments to commands, for asking questions, and printing brief
        !          12251: messages (including error messages).  @xref{Echo Area}.
        !          12252: 
        !          12253: @item Echoing
        !          12254: Echoing is acknowledging the receipt of commands by displaying them
        !          12255: (in the echo area).  Emacs never echoes single-character keys; longer
        !          12256: keys echo only if you pause while typing them.
        !          12257: 
        !          12258: @item Error Messages
        !          12259: Error messages are single lines of output printed by Emacs when the
        !          12260: user asks for something impossible to do (such as, killing text
        !          12261: forward when point is at the end of the buffer).  They appear in the
        !          12262: echo area, accompanied by a beep.
        !          12263: 
        !          12264: @item @key{ESC}
        !          12265: @key{ESC} is a character, used to end incremental searches and as a
        !          12266: prefix for typing Meta characters on keyboards lacking a @key{META}
        !          12267: key.
        !          12268: 
        !          12269: @item Fill Prefix
        !          12270: The fill prefix is a string that should be expected at the beginning
        !          12271: of each line when filling is done.  It is not regarded as part of the
        !          12272: text to be filled.  @xref{Filling}.
        !          12273: 
        !          12274: @item Filling
        !          12275: Filling text means moving text from line to line so that all the lines
        !          12276: are approximately the same length.  @xref{Filling}.
        !          12277: 
        !          12278: @item Global
        !          12279: Global means `independent of the current environment; in effect
        !          12280: throughout Emacs'.  It is the opposite of local (q.v.@:).  Particular
        !          12281: examples of the use of `global' appear below.
        !          12282: 
        !          12283: @item Global Abbrev
        !          12284: A global definition of an abbrev (q.v.@:) is effective in all major
        !          12285: modes that do not have local (q.v.@:) definitions for the same abbrev.
        !          12286: @xref{Abbrevs}.
        !          12287: 
        !          12288: @item Global Keymap
        !          12289: The global keymap (q.v.@:) contains key bindings that are in effect
        !          12290: except when overridden by local key bindings in a major mode's local
        !          12291: keymap (q.v.@:).  @xref{Keymaps}.
        !          12292: 
        !          12293: @item Global Substitution
        !          12294: Global substitution means replacing each occurrence of one string by
        !          12295: another string through a large amount of text.  @xref{Replace}.
        !          12296: 
        !          12297: @item Global Variable
        !          12298: The global value of a variable (q.v.@:) takes effect in all buffers
        !          12299: that do not have their own local (q.v.@:) values for the variable.
        !          12300: @xref{Variables}.
        !          12301: 
        !          12302: @item Graphic Character
        !          12303: Graphic characters are those assigned pictorial images rather than
        !          12304: just names.  All the non-Meta (q.v.@:) characters except for the
        !          12305: Control (q.v.@:) characters are graphic characters.  These include
        !          12306: letters, digits, punctuation, and spaces; they do not include
        !          12307: @key{RET} or @key{ESC}.  In Emacs, typing a graphic character inserts
        !          12308: that character (in ordinary editing modes).  @xref{Basic,,Basic Editing}.
        !          12309: 
        !          12310: @item Grinding
        !          12311: Grinding means adjusting the indentation in a program to fit the
        !          12312: nesting structure.  @xref{Indentation,Grinding}.
        !          12313: 
        !          12314: @item Hardcopy
        !          12315: Hardcopy means printed output.  Emacs has commands for making printed
        !          12316: listings of text in Emacs buffers.  @xref{Hardcopy}.
        !          12317: 
        !          12318: @item @key{HELP}
        !          12319: You can type @key{HELP} at any time to ask what options you have, or
        !          12320: to ask what any command does.  @key{HELP} is really @kbd{Control-h}.
        !          12321: @xref{Help}.
        !          12322: 
        !          12323: @item Indentation
        !          12324: Indentation means blank space at the beginning of a line.  Most
        !          12325: programming languages have conventions for using indentation to
        !          12326: illuminate the structure of the program, and Emacs has special
        !          12327: features to help you set up the correct indentation.
        !          12328: @xref{Indentation}.
        !          12329: 
        !          12330: @item Insertion
        !          12331: Insertion means copying text into the buffer, either from the keyboard
        !          12332: or from some other place in Emacs.
        !          12333: 
        !          12334: @item Justification
        !          12335: Justification means adding extra spaces to lines of text to make them
        !          12336: come exactly to a specified width.  @xref{Filling,Justification}.
        !          12337: 
        !          12338: @item Keyboard Macros
        !          12339: Keyboard macros are a way of defining new Emacs commands from
        !          12340: sequences of existing ones, with no need to write a Lisp program.
        !          12341: @xref{Keyboard Macros}.
        !          12342: 
        !          12343: @item Key
        !          12344: A key is a character or sequence of characters which, when typed by
        !          12345: the user, fully specifies one action to be performed by Emacs.  For
        !          12346: example, @kbd{X} and @kbd{Control-f} and @kbd{Control-x m} are keys.
        !          12347: Keys derive their meanings from being bound (q.v.@:) to commands
        !          12348: (q.v.@:).  @xref{Keys}.
        !          12349: 
        !          12350: @item Keymap
        !          12351: The keymap is the data structure that records the bindings (q.v.@:) of
        !          12352: keys to the commands that they run.  For example, the keymap binds the
        !          12353: character @kbd{C-n} to the command function @code{next-line}.
        !          12354: @xref{Keymaps}.
        !          12355: 
        !          12356: @item Kill Ring
        !          12357: The kill ring is where all text you have killed recently is saved.
        !          12358: You can reinsert any of the killed text still in the ring; this is
        !          12359: called yanking (q.v.@:).  @xref{Yanking}.
        !          12360: 
        !          12361: @item Killing
        !          12362: Killing means erasing text and saving it on the kill ring so it can be
        !          12363: yanked (q.v.@:) later.  Most Emacs commands to erase text do killing,
        !          12364: as opposed to deletion (q.v.@:).  @xref{Killing}.
        !          12365: 
        !          12366: @item Killing Jobs
        !          12367: Killing a job (such as, an invocation of Emacs) means making it cease
        !          12368: to exist.  Any data within it, if not saved in a file, is lost.
        !          12369: @xref{Exiting}.
        !          12370: 
        !          12371: @item List
        !          12372: A list is, approximately, a text string beginning with an open
        !          12373: parenthesis and ending with the matching close parenthesis.  In C mode
        !          12374: and other non-Lisp mode groupings surrounded by other kinds of matched
        !          12375: delimiters appropriate to the language, such as braces, are also
        !          12376: considered lists.  Emacs has special commands for many operations on
        !          12377: lists.  @xref{Lists}.
        !          12378: 
        !          12379: @item Local
        !          12380: Local means `in effect only in a particular context'; the relevant
        !          12381: kind of context is a particular function execution, a particular
        !          12382: buffer, or a particular major mode.  It is the opposite of `global'
        !          12383: (q.v.@:).  Specific uses of `local' in Emacs terminology appear below.
        !          12384: 
        !          12385: @item Local Abbrev
        !          12386: A local abbrev definition is effective only if a particular major mode
        !          12387: is selected.  In that major mode, it overrides any global definition
        !          12388: for the same abbrev.  @xref{Abbrevs}.
        !          12389: 
        !          12390: @item Local Keymap
        !          12391: A local keymap is used in a particular major mode; the key bindings
        !          12392: (q.v.@:) in the current local keymap override global bindings of the
        !          12393: same keys.  @xref{Keymaps}.
        !          12394: 
        !          12395: @item Local Variable
        !          12396: A local value of a variable (q.v.@:) applies to only one buffer.
        !          12397: @xref{Locals}.
        !          12398: 
        !          12399: @item M-
        !          12400: @kbd{M-} in the name of a character is an abbreviation for @key{META},
        !          12401: one of the modifier keys that can accompany any character.
        !          12402: @xref{Characters}.
        !          12403: 
        !          12404: @item M-C-
        !          12405: @samp{M-C-} in the name of a character is an abbreviation for
        !          12406: Control-Meta; it means the same thing as @samp{C-M-}.
        !          12407: @xref{Characters,C-M-}.
        !          12408: 
        !          12409: @item M-x
        !          12410: @kbd{M-x} is the key which is used to call an Emacs command by name.
        !          12411: This is how commands that are not bound to keys are called.
        !          12412: @xref{M-x}.
        !          12413: 
        !          12414: @item Mail
        !          12415: Mail means messages sent from one user to another through the computer
        !          12416: system, to be read at the recipient's convenience.  Emacs has commands for
        !          12417: composing and sending mail, and for reading and editing the mail you have
        !          12418: received.  @xref{Sending Mail}.
        !          12419: 
        !          12420: @item Major Mode
        !          12421: The major modes are a mutually exclusive set of options each of which
        !          12422: configures Emacs for editing a certain sort of text.  Ideally, each
        !          12423: programming language has its own major mode.  @xref{Major Modes}.
        !          12424: 
        !          12425: @item Mark
        !          12426: The mark points to a position in the text.  It specifies one end of
        !          12427: the region (q.v.@:), point being the other end.  Many commands operate
        !          12428: on all the text from point to the mark.  @xref{Mark}.
        !          12429: 
        !          12430: @item Mark Ring
        !          12431: The mark ring is used to hold several recent previous locations of the
        !          12432: mark, just in case you want to move back to them.  @xref{Mark Ring}.
        !          12433: 
        !          12434: @item Message
        !          12435: See `mail'.
        !          12436: 
        !          12437: @item Meta
        !          12438: Meta is the name of a modifier bit which a command character may have.
        !          12439: It is present in a character if the character is typed with the
        !          12440: @key{META} key held down.  Such characters are given names that start
        !          12441: with @kbd{Meta-}.  For example, @kbd{Meta-<} is typed by holding down
        !          12442: @key{META} and typing @kbd{<} (which itself is done, on most terminals,
        !          12443: by holding down @key{SHIFT} and typing @kbd{,}).  @xref{Characters,Meta}.
        !          12444: 
        !          12445: @item Meta Character
        !          12446: A Meta character is one whose character code includes the Meta bit.
        !          12447: 
        !          12448: @item Minibuffer
        !          12449: The minibuffer is the window that appears when necessary inside the
        !          12450: echo area (q.v.@:), used for reading arguments to commands.
        !          12451: @xref{Minibuffer}.
        !          12452: 
        !          12453: @item Minor Mode
        !          12454: A minor mode is an optional feature of Emacs which can be switched on
        !          12455: or off independently of all other features.  Each minor mode has a
        !          12456: command to turn it on or off.  @xref{Minor Modes}.
        !          12457: 
        !          12458: @item Mode Line
        !          12459: The mode line is the line at the bottom of each text window (q.v.@:),
        !          12460: which gives status information on the buffer displayed in that window.
        !          12461: @xref{Mode Line}.
        !          12462: 
        !          12463: @item Modified Buffer
        !          12464: A buffer (q.v.@:) is modified if its text has been changed since the
        !          12465: last time the buffer was saved (or since when it was created, if it
        !          12466: has never been saved).  @xref{Saving}.
        !          12467: 
        !          12468: @item Moving Text
        !          12469: Moving text means erasing it from one place and inserting it in
        !          12470: another.  This is done by killing (q.v.@:) and then yanking (q.v.@:).
        !          12471: @xref{Killing}.
        !          12472: 
        !          12473: @item Named Mark
        !          12474: A named mark is a register (q.v.@:) in its role of recording a
        !          12475: location in text so that you can move point to that location.
        !          12476: @xref{Registers}.
        !          12477: 
        !          12478: @item Narrowing
        !          12479: Narrowing means creating a restriction (q.v.@:) that limits editing in
        !          12480: the current buffer to only a part of the text in the buffer.  Text
        !          12481: outside that part is inaccessible to the user until the boundaries are
        !          12482: widened again, but it is still there, and saving the file saves it
        !          12483: all.  @xref{Narrowing}.
        !          12484: 
        !          12485: @item Newline
        !          12486: @key{LFD} characters in the buffer terminate lines of text and are
        !          12487: called newlines.  @xref{Characters,Newline}.
        !          12488: 
        !          12489: @item Numeric Argument
        !          12490: A numeric argument is a number, specified before a command, to change
        !          12491: the effect of the command.  Often the numeric argument serves as a
        !          12492: repeat count.  @xref{Arguments}.
        !          12493: 
        !          12494: @item Option
        !          12495: An option is a variable (q.v.@:) that exists so that you can customize
        !          12496: Emacs by giving it a new value.  @xref{Variables}.
        !          12497: 
        !          12498: @item Overwrite Mode
        !          12499: Overwrite mode is a minor mode.  When it is enabled, ordinary text
        !          12500: characters replace the existing text after point rather than pushing
        !          12501: it to the right.  @xref{Minor Modes}.
        !          12502: 
        !          12503: @item Page
        !          12504: A page is a unit of text, delimited by formfeed characters (ASCII
        !          12505: Control-L, code 014) coming at the beginning of a line.  Some Emacs
        !          12506: commands are provided for moving over and operating on pages.
        !          12507: @xref{Pages}.
        !          12508: 
        !          12509: @item Paragraphs
        !          12510: Paragraphs are the medium-size unit of English text.  There are
        !          12511: special Emacs commands for moving over and operating on paragraphs.
        !          12512: @xref{Paragraphs}.
        !          12513: 
        !          12514: @item Parsing
        !          12515: We say that Emacs parses words or expressions in the text being
        !          12516: edited.  Really, all it knows how to do is find the other end of a
        !          12517: word or expression.  @xref{Syntax}.
        !          12518: 
        !          12519: @item Point
        !          12520: Point is the place in the buffer at which insertion and deletion
        !          12521: occur.  Point is considered to be between two characters, not at one
        !          12522: character.  The terminal's cursor (q.v.@:) indicates the location of
        !          12523: point.  @xref{Basic,Point}.
        !          12524: 
        !          12525: @item Prefix Key
        !          12526: A prefix key is a key (q.v.@:) whose sole function is to introduce a
        !          12527: set of multi-character keys.  @kbd{Control-x} is an example of prefix
        !          12528: key; thus, any two-character sequence starting with @kbd{C-x} is also
        !          12529: a legitimate key.  @xref{Keys}.
        !          12530: 
        !          12531: @item Prompt
        !          12532: A prompt is text printed to ask the user for input.  Printing a prompt
        !          12533: is called prompting.  Emacs prompts always appear in the echo area
        !          12534: (q.v.@:).  One kind of prompting happens when the minibuffer is used
        !          12535: to read an argument (@pxref{Minibuffer}); the echoing which happens
        !          12536: when you pause in the middle of typing a multicharacter key is also a
        !          12537: kind of prompting (@pxref{Echo Area}).
        !          12538: 
        !          12539: @item Quitting
        !          12540: Quitting means cancelling a partially typed command or a running
        !          12541: command, using @kbd{C-g}.  @xref{Quitting}.
        !          12542: 
        !          12543: @item Quoting
        !          12544: Quoting means depriving a character of its usual special significance.
        !          12545: In Emacs this is usually done with @kbd{Control-q}.  What constitutes special
        !          12546: significance depends on the context and on convention.  For example,
        !          12547: an ``ordinary'' character as an Emacs command inserts itself; so in
        !          12548: this context, a special character is any character that does not
        !          12549: normally insert itself (such as @key{DEL}, for example), and quoting
        !          12550: it makes it insert itself as if it were not special.  Not all contexts
        !          12551: allow quoting.  @xref{Basic,Quoting,Basic Editing}.
        !          12552: 
        !          12553: @item Read-only Buffer
        !          12554: A read-only buffer is one whose text you are not allowed to change.
        !          12555: Normally Emacs makes buffers read-only when they contain text which
        !          12556: has a special significance to Emacs; for example, Dired buffers.
        !          12557: Visiting a file that is write protected also makes a read-only buffer.
        !          12558: @xref{Buffers}.
        !          12559: 
        !          12560: @item Recursive Editing Level
        !          12561: A recursive editing level is a state in which part of the execution of
        !          12562: a command involves asking the user to edit some text.  This text may
        !          12563: or may not be the same as the text to which the command was applied.
        !          12564: The mode line indicates recursive editing levels with square brackets
        !          12565: (@samp{[} and @samp{]}).  @xref{Recursive Edit}.
        !          12566: 
        !          12567: @item Redisplay
        !          12568: Redisplay is the process of correcting the image on the screen to
        !          12569: correspond to changes that have been made in the text being edited.
        !          12570: @xref{Screen,Redisplay}.
        !          12571: 
        !          12572: @item Region
        !          12573: The region is the text between point (q.v.@:) and the mark (q.v.@:).
        !          12574: Many commands operate on the text of the region.  @xref{Mark,Region}.
        !          12575: 
        !          12576: @item Registers
        !          12577: Registers are named slots in which text or buffer positions or
        !          12578: rectangles can be saved for later use.  @xref{Registers}.
        !          12579: 
        !          12580: @item Replacement
        !          12581: See `global substitution'.
        !          12582: 
        !          12583: @item Restriction
        !          12584: A buffer's restriction is the amount of text, at the beginning or the
        !          12585: end of the buffer, that is temporarily invisible and inaccessible.
        !          12586: Giving a buffer a nonzero amount of restriction is called narrowing
        !          12587: (q.v.).  @xref{Narrowing}.
        !          12588: 
        !          12589: @item @key{RET}
        !          12590: @key{RET} is a character than in Emacs runs the command to insert a
        !          12591: newline into the text.  It is also used to terminate most arguments
        !          12592: read in the minibuffer (q.v.@:).  @xref{Characters,Return}.
        !          12593: 
        !          12594: @item Saving
        !          12595: Saving a buffer means copying its text into the file that was visited
        !          12596: (q.v.@:) in that buffer.  This is the way text in files actually gets
        !          12597: changed by your Emacs editing.  @xref{Saving}.
        !          12598: 
        !          12599: @item Scrolling
        !          12600: Scrolling means shifting the text in the Emacs window so as to see a
        !          12601: different part of the buffer.  @xref{Display,Scrolling}.
        !          12602: 
        !          12603: @item Searching
        !          12604: Searching means moving point to the next occurrence of a specified
        !          12605: string.  @xref{Search}.
        !          12606: 
        !          12607: @item Selecting
        !          12608: Selecting a buffer means making it the current (q.v.@:) buffer.
        !          12609: @xref{Buffers,Selecting}.
        !          12610: 
        !          12611: @item Self-documentation
        !          12612: Self-documentation is the feature of Emacs which can tell you what any
        !          12613: command does, or give you a list of all commands related to a topic
        !          12614: you specify.  You ask for self-documentation with the @key{HELP}
        !          12615: character.  @xref{Help}.
        !          12616: 
        !          12617: @item Sentences
        !          12618: Emacs has commands for moving by or killing by sentences.
        !          12619: @xref{Sentences}.
        !          12620: 
        !          12621: @item Sexp
        !          12622: A sexp (short for `s-expression') is the basic syntactic unit of Lisp
        !          12623: in its textual form: either a list, or Lisp atom.  Many Emacs commands
        !          12624: operate on sexps.  The term `sexp' is generalized to languages other
        !          12625: than Lisp, to mean a syntactically recognizable expression.
        !          12626: @xref{Lists,Sexps}.
        !          12627: 
        !          12628: @item Simultaneous Editing
        !          12629: Simultaneous editing means two users modifying the same file at once.
        !          12630: Simultaneous editing if not detected can cause one user to lose his
        !          12631: work.  Emacs detects all cases of simultaneous editing and warns the
        !          12632: user to investigate them.  @xref{Interlocking,,Simultaneous Editing}.
        !          12633: 
        !          12634: @item String
        !          12635: A string is a kind of Lisp data object which contains a sequence of
        !          12636: characters.  Many Emacs variables are intended to have strings as
        !          12637: values.  The Lisp syntax for a string consists of the characters in
        !          12638: the string with a @samp{"} before and another @samp{"} after.  A
        !          12639: @samp{"} that is part of the string must be written as @samp{\"} and a
        !          12640: @samp{\} that is part of the string must be written as @samp{\\}.  All
        !          12641: other characters, including newline, can be included just by writing
        !          12642: them inside the string; however, escape sequences as in C, such as
        !          12643: @samp{\n} for newline or @samp{\241} using an octal character code,
        !          12644: are allowed as well.
        !          12645: 
        !          12646: @item String Substitution
        !          12647: See `global substitution'.
        !          12648: 
        !          12649: @item Syntax Table
        !          12650: The syntax table tells Emacs which characters are part of a word,
        !          12651: which characters balance each other like parentheses, etc.
        !          12652: @xref{Syntax}.
        !          12653: 
        !          12654: @item Tag Table
        !          12655: A tag table is a file that serves as an index to the function
        !          12656: definitions in one or more other files.  @xref{Tags}.
        !          12657: 
        !          12658: @item Termscript File
        !          12659: A termscript file contains a record of all characters sent by Emacs to
        !          12660: the terminal.  It is used for tracking down bugs in Emacs redisplay.
        !          12661: Emacs does not make a termscript file unless you tell it to.
        !          12662: @xref{Bugs}.
        !          12663: 
        !          12664: @item Text
        !          12665: Two meanings (@pxref{Text}):
        !          12666: 
        !          12667: @itemize @bullet
        !          12668: @item
        !          12669: Data consisting of a sequence of characters.  The contents of an
        !          12670: Emacs buffer are always text in this sense.
        !          12671: @item
        !          12672: Data consisting of written human language, as opposed to programs,
        !          12673: or following the stylistic conventions of human language.
        !          12674: @end itemize
        !          12675: 
        !          12676: @item Top Level
        !          12677: Top level is the normal state of Emacs, in which you are editing the
        !          12678: text of the file you have visited.  You are at top level whenever you
        !          12679: are not in a recursive editing level (q.v.@:) or the minibuffer
        !          12680: (q.v.@:), and not in the middle of a command.  You can get back to top
        !          12681: level by aborting (q.v.@:) and quitting (q.v.@:).  @xref{Quitting}.
        !          12682: 
        !          12683: @item Transposition
        !          12684: Transposing two units of text means putting each one into the place
        !          12685: formerly occupied by the other.  There are Emacs commands to transpose
        !          12686: two adjacent characters, words, sexps (q.v.@:) or lines
        !          12687: (@pxref{Transpose}).
        !          12688: 
        !          12689: @item Truncation
        !          12690: Truncating text lines in the display means leaving out any text on a
        !          12691: line that does not fit within the right margin of the window
        !          12692: displaying it.  See also `continuation line'.
        !          12693: @xref{Basic,Truncation,Basic Editing}.
        !          12694: 
        !          12695: @item Undoing
        !          12696: Undoing means making your previous editing go in reverse, bringing
        !          12697: back the text that existed earlier in the editing session.
        !          12698: @xref{Undo}.
        !          12699: 
        !          12700: @item Variable
        !          12701: A variable is an object in Lisp that can store an arbitrary value.
        !          12702: Emacs uses some variables for internal purposes, and has others (known
        !          12703: as `options' (q.v.@:)) just so that you can set their values to
        !          12704: control the behavior of Emacs.  The variables used in Emacs that you
        !          12705: are likely to be interested in are listed in the Variables Index in
        !          12706: this manual.  @xref{Variables}, for information on variables.
        !          12707: 
        !          12708: @item Visiting
        !          12709: Visiting a file means loading its contents into a buffer (q.v.@:)
        !          12710: where they can be edited.  @xref{Visiting}.
        !          12711: 
        !          12712: @item Whitespace
        !          12713: Whitespace is any run of consecutive formatting characters (space,
        !          12714: tab, newline, and backspace).
        !          12715: 
        !          12716: @item Widening
        !          12717: Widening is removing any restriction (q.v.@:) on the current buffer;
        !          12718: it is the opposite of narrowing (q.v.@:).  @xref{Narrowing}.
        !          12719: 
        !          12720: @item Window
        !          12721: Emacs divides the screen into one or more windows, each of which can
        !          12722: display the contents of one buffer (q.v.@:) at any time.
        !          12723: @xref{Screen}, for basic information on how Emacs uses the screen.
        !          12724: @xref{Windows}, for commands to control the use of windows.
        !          12725: 
        !          12726: @item Word Abbrev
        !          12727: Synonymous with `abbrev'.
        !          12728: 
        !          12729: @item Word Search
        !          12730: Word search is searching for a sequence of words, considering the
        !          12731: punctuation between them as insignificant.  @xref{Word Search}.
        !          12732: 
        !          12733: @item Yanking
        !          12734: Yanking means reinserting text previously killed.  It can be used to
        !          12735: undo a mistaken kill, or for copying or moving text.  @xref{Yanking}.
        !          12736: @end table
        !          12737: 
        !          12738: @node Key Index, Command Index, Glossary, Top
        !          12739: @unnumbered Key (Character) Index
        !          12740: @printindex ky
        !          12741: 
        !          12742: @node Command Index, Variable Index, Key Index, Top
        !          12743: @unnumbered Command and Function Index
        !          12744: @printindex fn
        !          12745: 
        !          12746: @node Variable Index, Concept Index, Command Index, Top
        !          12747: @unnumbered Variable Index
        !          12748: @printindex vr
        !          12749: 
        !          12750: @node Concept Index, Screen, Variable Index, Top
        !          12751: @unnumbered Concept Index
        !          12752: @printindex cp
        !          12753: 
        !          12754: @summarycontents
        !          12755: @contents
        !          12756: @bye