Return to emacs.texi CVS log

Up to [Apple XNU] / GNUtools / emacs / man

Annotation of GNUtools/emacs/man/emacs.texi, revision 1.1

1.1     ! root        1: \input texinfo.tex  @c -*-texinfo-*-
        !             2: @c %**start of header
        !             3: @setfilename ../info/emacs
        !             4: @settitle GNU Emacs Manual
        !             5: @setchapternewpage odd
        !             6: @smallbook
        !             7: @c %**end of header
        !             8: 
        !             9: @finalout
        !            10: 
        !            11: @c
        !            12: @tex
        !            13: %%%% This is special for the Emacs Manual %%%%
        !            14: %%%% Robert J. Chassell 10 June 1992
        !            15: 
        !            16: %%%% Use less indentation for Table of Contents
        !            17: \global\tocindent = 1.5pc
        !            18: \global\def\labelspace{\hskip.5em \relax}
        !            19: @end tex
        !            20: @c
        !            21: 
        !            22: @ifinfo
        !            23: This file documents the GNU Emacs editor.
        !            24: 
        !            25: Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman.
        !            26: 
        !            27: Permission is granted to make and distribute verbatim copies of
        !            28: this manual provided the copyright notice and this permission notice
        !            29: are preserved on all copies.
        !            30: 
        !            31: @ignore
        !            32: Permission is granted to process this file through Tex and print the
        !            33: results, provided the printed document carries copying permission
        !            34: notice identical to this one except for the removal of this paragraph
        !            35: (this paragraph not being relevant to the printed manual).
        !            36: 
        !            37: @end ignore
        !            38: Permission is granted to copy and distribute modified versions of this
        !            39: manual under the conditions for verbatim copying, provided also that the
        !            40: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU
        !            41: General Public License'' are included exactly as in the original, and
        !            42: provided that the entire resulting derived work is distributed under the
        !            43: terms of a permission notice identical to this one.
        !            44: 
        !            45: Permission is granted to copy and distribute translations of this manual
        !            46: into another language, under the above conditions for modified versions,
        !            47: except that the sections entitled ``The GNU Manifesto'',
        !            48: ``Distribution'' and ``GNU General Public License'' may be included in a
        !            49: translation approved by the author instead of in the original English.
        !            50: @end ifinfo
        !            51: @c
        !            52: @c
        !            53: @titlepage
        !            54: @sp 6
        !            55: @center @titlefont{GNU Emacs Manual}
        !            56: @sp 4
        !            57: @center Seventh Edition, Emacs Version 18.58
        !            58: @sp 1
        !            59: @center for Unix Users
        !            60: @sp 1
        !            61: @center February 1988, revised September 1992
        !            62: @center (General Public License upgraded, January 1991)
        !            63: @sp 5
        !            64: @center Richard M. Stallman
        !            65: @page
        !            66: @vskip 0pt plus 1filll
        !            67: Copyright @copyright{} 1985, 1986, 1988, 1992 Richard M. Stallman.
        !            68: 
        !            69: Permission is granted to make and distribute verbatim copies of
        !            70: this manual provided the copyright notice and this permission notice
        !            71: are preserved on all copies.
        !            72: 
        !            73: Permission is granted to copy and distribute modified versions of this
        !            74: manual under the conditions for verbatim copying, provided also that the
        !            75: sections entitled ``The GNU Manifesto'', ``Distribution'' and ``GNU
        !            76: General Public License'' are included exactly as in the original, and
        !            77: provided that the entire resulting derived work is distributed under the
        !            78: terms of a permission notice identical to this one.
        !            79: 
        !            80: Permission is granted to copy and distribute translations of this manual
        !            81: into another language, under the above conditions for modified versions,
        !            82: except that the sections entitled ``The GNU Manifesto'',
        !            83: ``Distribution'' and ``GNU General Public License'' may be included in a
        !            84: translation approved by the author instead of in the original English.
        !            85: @sp 2
        !            86: Cover art by Etienne Suvasa.
        !            87: @end titlepage
        !            88: @page
        !            89: @ifinfo
        !            90: @node Top, Distrib,, (DIR)
        !            91: @top The Emacs Editor
        !            92: 
        !            93: Emacs is the extensible, customizable, self-documenting real-time
        !            94: display editor.  This Info file describes how to edit with Emacs
        !            95: and some of how to customize it, but not how to extend it.
        !            96: 
        !            97: @end ifinfo
        !            98: @menu
        !            99: * Distrib::     How to get the latest Emacs distribution.
        !           100: * License::     The GNU General Public License gives you permission
        !           101:                to redistribute GNU Emacs on certain terms; and also
        !           102:                explains that there is no warranty.
        !           103: * Intro::       An introduction to Emacs concepts.
        !           104: * Glossary::    The glossary.
        !           105: * Version 19::  Changes coming in Emacs version 19, to be released.
        !           106: * Manifesto::   What's GNU?  Gnu's Not Unix!
        !           107: 
        !           108: Indexes, nodes containing large menus
        !           109: * Key Index::      An item for each standard Emacs key sequence.
        !           110: * Command Index::  An item for each command name.
        !           111: * Variable Index:: An item for each documented variable.
        !           112: * Concept Index::  An item for each concept.
        !           113: 
        !           114: Important General Concepts
        !           115: * Screen::      How to interpret what you see on the screen.
        !           116: * Characters::  Emacs's character sets for file contents and for keyboard.
        !           117: * Keys::        Key sequences: what you type to request one editing action.
        !           118: * Commands::    Commands: named functions run by key sequences to do editing.
        !           119: * Entering Emacs::    Starting Emacs from the shell.
        !           120: * Command Switches::  Hairy startup options.
        !           121: * Exiting::     Stopping or killing Emacs.
        !           122: * Basic::       The most basic editing commands.
        !           123: * Undo::        Undoing recently made changes in the text.
        !           124: * Minibuffer::  Entering arguments that are prompted for.
        !           125: * M-x::         Invoking commands by their names.
        !           126: * Help::        Commands for asking Emacs about its commands.
        !           127: 
        !           128: Important Text-Changing Commands
        !           129: * Mark::        The mark: how to delimit a ``region'' of text.
        !           130: * Killing::     Killing text.
        !           131: * Yanking::     Recovering killed text.  Moving text.
        !           132: * Accumulating Text::
        !           133:                 Other ways of copying text.
        !           134: * Rectangles::  Operating on the text inside a rectangle on the screen.
        !           135: * Registers::   Saving a text string or a location in the buffer.
        !           136: * Display::     Controlling what text is displayed.
        !           137: * Search::      Finding or replacing occurrences of a string.
        !           138: * Fixit::       Commands especially useful for fixing typos.
        !           139: 
        !           140: Larger Units of Text
        !           141: * Files::       All about handling files.
        !           142: * Buffers::     Multiple buffers; editing several files at once.
        !           143: * Windows::     Viewing two pieces of text at once.
        !           144: 
        !           145: Advanced Features
        !           146: * Major Modes:: Text mode vs. Lisp mode vs. C mode ...
        !           147: * Indentation:: Editing the white space at the beginnings of lines.
        !           148: * Text::        Commands and modes for editing English.
        !           149: * Programs::    Commands and modes for editing programs.
        !           150: * Compiling/Testing::
        !           151:                Compiling, running and debugging programs.
        !           152: * Abbrevs::     How to define text abbreviations to reduce
        !           153:                  the number of characters you must type.
        !           154: * Picture::     Editing pictures made up of characters
        !           155:                  using the quarter-plane screen model.
        !           156: * Sending Mail::Sending mail in Emacs.
        !           157: * Rmail::       Reading mail in Emacs.
        !           158: * Recursive Edit::
        !           159:                 A command can allow you to do editing
        !           160:                  "within the command".  This is called a
        !           161:                  `recursive editing level'.
        !           162: * Narrowing::   Restricting display and editing to a portion
        !           163:                  of the buffer.
        !           164: * Sorting::    Sorting lines, paragraphs or pages within Emacs.
        !           165: * Shell::       Executing shell commands from Emacs.
        !           166: * Hardcopy::   Printing buffers or regions.
        !           167: * Dissociated Press::  Dissociating text for fun.
        !           168: * Amusements::         Various games and hacks.
        !           169: * Emulation::         Emulating some other editors with Emacs.
        !           170: * Customization::      Modifying the behavior of Emacs.
        !           171: 
        !           172: Recovery from Problems.
        !           173: * Quitting::    Quitting and aborting.
        !           174: * Lossage::     What to do if Emacs is hung or malfunctioning.
        !           175: * Bugs::        How and when to report a bug.
        !           176: 
        !           177: Here are some other nodes which are really inferiors of the ones
        !           178: already listed, mentioned here so you can get to them in one step:
        !           179: 
        !           180: Subnodes of Screen
        !           181: * Point::      The place in the text where editing commands operate.
        !           182: * Echo Area::   Short messages appear at the bottom of the screen.
        !           183: * Mode Line::  Interpreting the mode line.
        !           184: 
        !           185: Subnodes of Basic
        !           186: * Blank Lines:: Commands to make or delete blank lines.
        !           187: * Continuation Lines:: Lines too wide for the screen.
        !           188: * Position Info::      What page, line, row, or column is point on?
        !           189: * Arguments::          Giving numeric arguments to commands.
        !           190: 
        !           191: Subnodes of Minibuffer
        !           192: * Minibuffer File::    Entering file names with the minibuffer.
        !           193: * Minibuffer Edit::    How to edit in the minibuffer.
        !           194: * Completion::  An abbreviation facility for minibuffer input.
        !           195: * Repetition::  Re-executing previous commands that used the minibuffer.
        !           196: 
        !           197: Subnodes of Mark
        !           198: * Setting Mark::       Commands to set the mark.
        !           199: * Using Region::       Summary of ways to operate on contents of the region.
        !           200: * Marking Objects::    Commands to put region around textual units.
        !           201: * Mark Ring::          Previous mark positions saved so you can go back there.
        !           202: 
        !           203: Subnodes of Yanking
        !           204: * Kill Ring::          Where killed text is stored.  Basic yanking.
        !           205: * Appending Kills::    Several kills in a row all yank together.
        !           206: * Earlier Kills::      Yanking something killed some time ago.
        !           207: 
        !           208: Subnodes of Registers
        !           209: * RegPos::             Saving positions in registers.
        !           210: * RegText::            Saving text in registers.
        !           211: * RegRect::            Saving rectangles in registers.
        !           212: 
        !           213: Subnodes of Display
        !           214: * Scrolling::             Moving text up and down in a window.
        !           215: * Horizontal Scrolling::   Moving text left and right in a window.
        !           216: * Selective Display::      Hiding lines with lots of indentation.
        !           217: * Display Vars::           Information on variables for customizing display.
        !           218: 
        !           219: Subnodes of Search
        !           220: * Incremental Search::     Search happens as you type the string.
        !           221: * Nonincremental Search::  Specify entire string and then search.
        !           222: * Word Search::           Search for sequence of words.
        !           223: * Regexp Search::         Search for match for a regexp.
        !           224: * Regexps::               Syntax of regular expressions.
        !           225: * Search Case::                   To ignore case while searching, or not.
        !           226: * Replace::               Search, and replace some or all matches.
        !           227: * Unconditional Replace::  Everything about replacement except for querying.
        !           228: * Query Replace::          How to use querying.
        !           229: * Other Repeating Search:: Operating on all matches for some regexp.
        !           230: 
        !           231: Subnodes of Fixit
        !           232: * Kill Errors:: Commands to kill a batch of recently entered text.
        !           233: * Transpose::   Exchanging two characters, words, lines, lists...
        !           234: * Fixing Case:: Correcting case of last word entered.
        !           235: * Spelling::    Apply spelling checker to a word, or a whole file.
        !           236: 
        !           237: Subnodes of Files
        !           238: * File Names::  How to type and edit file name arguments.
        !           239: * Visiting::    Visiting a file prepares Emacs to edit the file.
        !           240: * Saving::      Saving makes your changes permanent.
        !           241: * Backup::      How Emacs saves the old version of your file.
        !           242: * Interlocking::How Emacs protects against simultaneous editing
        !           243:                  of one file by two users.
        !           244: * Reverting::   Reverting cancels all the changes not saved.
        !           245: * Auto Save::   Auto Save periodically protects against loss of data.
        !           246: * ListDir::     Listing the contents of a file directory.
        !           247: * Dired::       ``Editing'' a directory to delete, rename, etc.
        !           248:                  the files in it.
        !           249: * Misc File Ops:: Other things you can do on files.
        !           250: 
        !           251: Subnodes of Buffers
        !           252: * Select Buffer::   Creating a new buffer or reselecting an old one.
        !           253: * List Buffers::    Getting a list of buffers that exist.
        !           254: * Misc Buffer::     Renaming; changing read-only status.
        !           255: * Kill Buffer::     Killing buffers you no longer need.
        !           256: * Several Buffers:: How to go through the list of all buffers
        !           257:                      and operate variously on several of them.
        !           258: 
        !           259: Subnodes of Windows
        !           260: * Basic Window::    Introduction to Emacs windows.
        !           261: * Split Window::    New windows are made by splitting existing windows.
        !           262: * Other Window::    Moving to another window or doing something to it.
        !           263: * Pop Up Window::   Finding a file or buffer in another window.
        !           264: * Change Window::   Deleting windows and changing their sizes.
        !           265: 
        !           266: Subnodes of Indentation
        !           267: * Indentation Commands:: Various commands and techniques for indentation.
        !           268: * Tab Stops::   You can set arbitrary "tab stops" and then
        !           269:                  indent to the next tab stop when you want to.
        !           270: * Just Spaces:: You can request indentation using just spaces.
        !           271: 
        !           272: Subnodes of Text
        !           273: * Text Mode::   The major mode for editing text files.
        !           274: * Nroff Mode::  The major mode for editing input to the formatter nroff.
        !           275: * TeX Mode::    The major mode for editing input to the formatter TeX.
        !           276: * Texinfo Mode::The major mode for editing input to the formatter Texinfo.
        !           277: * Outline Mode::The major mode for editing outlines.
        !           278: * Words::       Moving over and killing words.
        !           279: * Sentences::   Moving over and killing sentences.
        !           280: * Paragraphs:: Moving over paragraphs.
        !           281: * Pages::      Moving over pages.
        !           282: * Filling::     Filling or justifying text
        !           283: * Case::        Changing the case of text
        !           284: 
        !           285: Subnodes of Programs
        !           286: * Program Modes::       Major modes for editing programs.
        !           287: * Lists::       Expressions with balanced parentheses.
        !           288:                  There are editing commands to operate on them.
        !           289: * Defuns::      Each program is made up of separate functions.
        !           290:                  There are editing commands to operate on them.
        !           291: * Grinding::    Adjusting indentation to show the nesting.
        !           292: * Matching::    Insertion of a close-delimiter flashes matching open.
        !           293: * Comments::    Inserting, killing and aligning comments.
        !           294: * Balanced Editing::    Inserting two matching parentheses at once, etc.
        !           295: * Lisp Completion::     Completion on symbol names in Lisp code.
        !           296: * Documentation::       Getting documentation of functions you plan to call.
        !           297: * Change Log::  Maintaining a change history for your program.
        !           298: * Tags::        Go direct to any function in your program in one
        !           299:                  command.  Tags remembers which file it is in.
        !           300: * Fortran::    Fortran mode and its special features.
        !           301: 
        !           302: Subnodes of Compiling/Testing
        !           303: * Compilation::       Compiling programs in languages other than Lisp
        !           304:                        (C, Pascal, etc.)
        !           305: * Lisp Modes::        Various modes for editing Lisp programs, with
        !           306:                        different facilities for running the Lisp programs.
        !           307: * Lisp Libraries::    Creating Lisp programs to run in Emacs.
        !           308: * Lisp Interaction::  Executing Lisp in an Emacs buffer.
        !           309: * Lisp Eval::         Executing a single Lisp expression in Emacs.
        !           310: * Lisp Debug::        Debugging Lisp programs running in Emacs.
        !           311: * External Lisp::     Communicating through Emacs with a separate Lisp.
        !           312: 
        !           313: Subnodes of Abbrevs
        !           314: * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
        !           315: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
        !           316: * Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
        !           317: * Saving Abbrevs::    Saving the entire list of abbrevs for another session.
        !           318: * Dynamic Abbrevs::   Abbreviations for words already in the buffer.
        !           319: 
        !           320: Subnodes of Picture
        !           321: * Basic Picture::     Basic concepts and simple commands of Picture mode.
        !           322: * Insert in Picture:: Controlling direction of cursor motion
        !           323:                        after "self-inserting" characters.
        !           324: * Tabs in Picture::   Various features for tab stops and indentation.
        !           325: * Rectangles in Picture:: Clearing and superimposing rectangles.
        !           326: 
        !           327: Subnodes of Sending Mail
        !           328: * Mail Format::       Format of the mail being composed.
        !           329: * Mail Headers::      Details of allowed mail header fields.
        !           330: * Mail Mode::         Special commands for editing mail being composed.
        !           331: 
        !           332: Subnodes of Rmail
        !           333: * Rmail Scrolling::   Scrolling through a message.
        !           334: * Rmail Motion::      Moving to another message.
        !           335: * Rmail Deletion::    Deleting and expunging messages.
        !           336: * Rmail Inbox::       How mail gets into the Rmail file.
        !           337: * Rmail Files::       Using multiple Rmail files.
        !           338: * Rmail Output::      Copying message out to files.
        !           339: * Rmail Labels::      Classifying messages by labeling them.
        !           340: * Rmail Summary::     Summaries show brief info on many messages.
        !           341: * Rmail Reply::       Sending replies to messages you are viewing.
        !           342: * Rmail Editing::     Editing message text and headers in Rmail.
        !           343: * Rmail Digest::      Extracting the messages from a digest message.
        !           344: 
        !           345: Subnodes of Shell
        !           346: * Single Shell::      Commands to run one shell command and return.
        !           347: * Interactive Shell:: Permanent shell taking input via Emacs.
        !           348: * Shell Mode::        Special Emacs commands used with permanent shell.
        !           349: 
        !           350: Subnodes of Customization
        !           351: * Minor Modes::       Each minor mode is one feature you can turn on
        !           352:                        independently of any others.
        !           353: * Variables::         Many Emacs commands examine Emacs variables
        !           354:                        to decide what to do; by setting variables,
        !           355:                        you can control their functioning.
        !           356: * Examining::         Examining or setting one variable's value.
        !           357: * Edit Options::      Examining or editing list of all variables' values.
        !           358: * Locals::            Per-buffer values of variables.
        !           359: * File Variables::    How files can specify variable values.
        !           360: * Keyboard Macros::   A keyboard macro records a sequence of keystrokes
        !           361:                        to be replayed with a single command.
        !           362: * Key Bindings::      The keymaps say what command each key runs.
        !           363:                        By changing them, you can "redefine keys".
        !           364: * Keymaps::           Definition of the keymap data structure.
        !           365: * Rebinding::         How to redefine one key's meaning conveniently.
        !           366: * Disabling::         Disabling a command means confirmation is required
        !           367:                        before it can be executed.  This is done to protect
        !           368:                        beginners from surprises.
        !           369: * Syntax::            The syntax table controls how words and expressions
        !           370:                        are parsed.
        !           371: * Init File::         How to write common customizations in the `.emacs' file.
        !           372: 
        !           373: Subnodes of Lossage (and recovery)
        !           374: * Stuck Recursive::   `[...]' in mode line around the parentheses.
        !           375: * Screen Garbled::    Garbage on the screen.
        !           376: * Text Garbled::      Garbage in the text.
        !           377: * Unasked-for Search::Spontaneous entry to incremental search.
        !           378: * Emergency Escape::  Emergency escape---
        !           379:                        What to do if Emacs stops responding.
        !           380: * Total Frustration:: When you are at your wits' end.
        !           381: @end menu
        !           382: 
        !           383: @iftex
        !           384: @unnumbered Preface
        !           385: 
        !           386:   This manual documents the use and simple customization of the
        !           387: Emacs editor.  The reader is not expected to be a programmer.  Even simple
        !           388: customizations do not require programming skill, but the user who is not
        !           389: interested in customizing can ignore the scattered customization hints.
        !           390: 
        !           391:   This is primarily a reference manual, but can also be used as a
        !           392: primer.  However, I recommend that the newcomer first use the on-line,
        !           393: learn-by-doing tutorial, which you get by running Emacs and typing
        !           394: @kbd{C-h t}.  With it, you learn Emacs by using Emacs on a specially
        !           395: designed file which describes commands, tells you when to try them,
        !           396: and then explains the results you see.  This gives a more vivid
        !           397: introduction than a printed manual.
        !           398: 
        !           399:   On first reading, just skim chapters one and two, which describe the
        !           400: notational conventions of the manual and the general appearance of the
        !           401: Emacs display screen.  Note which questions are answered in these chapters,
        !           402: so you can refer back later.  After reading chapter four you should
        !           403: practice the commands there.  The next few chapters describe fundamental
        !           404: techniques and concepts that are used constantly.  You need to understand
        !           405: them thoroughly, experimenting with them if necessary.
        !           406: 
        !           407:   To find the documentation on a particular command, look in the index.
        !           408: Keys (character commands) and command names have separate indexes.  There
        !           409: is also a glossary, with a cross reference for each term.
        !           410: 
        !           411: @ignore
        !           412:   If you know vaguely what the command
        !           413: does, look in the command summary.  The command summary contains a line or
        !           414: two about each command, and a cross reference to the section of the
        !           415: manual that describes the command in more detail; related commands
        !           416: are grouped together.
        !           417: @end ignore
        !           418: 
        !           419:   This manual comes in two forms: the published form and the Info form.
        !           420: The Info form is for on-line perusal with the @code{info} program; it is
        !           421: distributed along with GNU Emacs.  Both forms contain substantially the
        !           422: same text and are generated from a common source file, which is also
        !           423: distributed along with GNU Emacs.
        !           424: 
        !           425:   GNU Emacs is a member of the Emacs editor family.  There are many Emacs
        !           426: editors, all sharing common principles of organization.  For information on
        !           427: the underlying philosophy of Emacs and the lessons learned from its
        !           428: development, write for a copy of AI memo 519a, ``Emacs, the Extensible,
        !           429: Customizable Self-Documenting Display Editor'', to Publications Department,
        !           430: Artificial Intelligence Lab, 545 Tech Square, Cambridge, MA 02139, USA.  At
        !           431: last report they charge $2.25 per copy.  Another useful publication is LCS
        !           432: TM-165, ``A Cookbook for an Emacs'', by Craig Finseth, available from
        !           433: Publications Department, Laboratory for Computer Science, 545 Tech Square,
        !           434: Cambridge, MA 02139, USA.  The price today is $3.
        !           435: 
        !           436: This edition of the manual is intended for use with GNU Emacs installed on
        !           437: Unix systems.  GNU Emacs can also be used on VMS systems, which have
        !           438: different file name syntax and do not support all GNU Emacs features.  A
        !           439: VMS edition of this manual may appear in the future.
        !           440: @end iftex
        !           441: 
        !           442: @node Distrib, License, Top, Top
        !           443: @unnumbered Distribution
        !           444: 
        !           445: GNU Emacs is @dfn{free}; this means that everyone is free to use it and
        !           446: free to redistribute it on a free basis.  GNU Emacs is not in the public
        !           447: domain; it is copyrighted and there are restrictions on its
        !           448: distribution, but these restrictions are designed to permit everything
        !           449: that a good cooperating citizen would want to do.  What is not allowed
        !           450: is to try to prevent others from further sharing any version of GNU
        !           451: Emacs that they might get from you.  The precise conditions are found in
        !           452: the GNU General Public License that comes with Emacs and also appears
        !           453: following this section.
        !           454: 
        !           455: The easiest way to get a copy of GNU Emacs is from someone else who has it.
        !           456: You need not ask for permission to do so, or tell any one else; just copy
        !           457: it.
        !           458: 
        !           459: If you have access to the Internet, you can get the latest distribution
        !           460: version of GNU Emacs from host @file{prep.ai.mit.edu} using anonymous
        !           461: login.  See the file @file{/u2/emacs/GETTING.GNU.SOFTWARE} on that host
        !           462: to find out about your options for copying and which files to use.
        !           463: 
        !           464: You may also receive GNU Emacs when you buy a computer.  Computer
        !           465: manufacturers are free to distribute copies on the same terms that apply to
        !           466: everyone else.  These terms require them to give you the full sources,
        !           467: including whatever changes they may have made, and to permit you to
        !           468: redistribute the GNU Emacs received from them under the usual terms of the
        !           469: General Public License.  In other words, the program must be free for you
        !           470: when you get it, not just free for the manufacturer.
        !           471: 
        !           472: If you cannot get a copy in any of those ways, you can order one from the
        !           473: Free Software Foundation.  Though Emacs itself is free, our distribution
        !           474: service is not.  An order form is included at the end of manuals printed by
        !           475: the Foundation.  It is also included in the file @file{etc/DISTRIB} in the
        !           476: Emacs distribution.  For further information, write to
        !           477: 
        !           478: @display
        !           479: Free Software Foundation
        !           480: 675 Mass Ave
        !           481: Cambridge, MA 02139
        !           482: USA
        !           483: @end display
        !           484: 
        !           485: The income from distribution fees goes to support the foundation's
        !           486: purpose: the development of more free software to distribute just like
        !           487: GNU Emacs.
        !           488: 
        !           489: If you find GNU Emacs useful, please @b{send a donation} to the Free
        !           490: Software Foundation.  This will help support development of the rest of the
        !           491: GNU system, and other useful software beyond that.  Your donation is tax
        !           492: deductible.
        !           493: 
        !           494: @node License, Intro, Distrib, Top
        !           495: @unnumbered GNU GENERAL PUBLIC LICENSE
        !           496: @center Version 1, February 1989
        !           497: @cindex license to copy Emacs
        !           498: @cindex General Public License
        !           499: 
        !           500: @display
        !           501: Copyright @copyright{} 1989 Free Software Foundation, Inc.
        !           502: 675 Mass Ave, Cambridge, MA 02139, USA
        !           503: 
        !           504: Everyone is permitted to copy and distribute verbatim copies
        !           505: of this license document, but changing it is not allowed.
        !           506: @end display
        !           507: 
        !           508: @unnumberedsec Preamble
        !           509: 
        !           510:   The license agreements of most software companies try to keep users
        !           511: at the mercy of those companies.  By contrast, our General Public
        !           512: License is intended to guarantee your freedom to share and change free
        !           513: software---to make sure the software is free for all its users.  The
        !           514: General Public License applies to the Free Software Foundation's
        !           515: software and to any other program whose authors commit to using it.
        !           516: You can use it for your programs, too.
        !           517: 
        !           518:   When we speak of free software, we are referring to freedom, not
        !           519: price.  Specifically, the General Public License is designed to make
        !           520: sure that you have the freedom to give away or sell copies of free
        !           521: software, that you receive source code or can get it if you want it,
        !           522: that you can change the software or use pieces of it in new free
        !           523: programs; and that you know you can do these things.
        !           524: 
        !           525:   To protect your rights, we need to make restrictions that forbid
        !           526: anyone to deny you these rights or to ask you to surrender the rights.
        !           527: These restrictions translate to certain responsibilities for you if you
        !           528: distribute copies of the software, or if you modify it.
        !           529: 
        !           530:   For example, if you distribute copies of a such a program, whether
        !           531: gratis or for a fee, you must give the recipients all the rights that
        !           532: you have.  You must make sure that they, too, receive or can get the
        !           533: source code.  And you must tell them their rights.
        !           534: 
        !           535:   We protect your rights with two steps: (1) copyright the software, and
        !           536: (2) offer you this license which gives you legal permission to copy,
        !           537: distribute and/or modify the software.
        !           538: 
        !           539:   Also, for each author's protection and ours, we want to make certain
        !           540: that everyone understands that there is no warranty for this free
        !           541: software.  If the software is modified by someone else and passed on, we
        !           542: want its recipients to know that what they have is not the original, so
        !           543: that any problems introduced by others will not reflect on the original
        !           544: authors' reputations.
        !           545: 
        !           546:   The precise terms and conditions for copying, distribution and
        !           547: modification follow.
        !           548: 
        !           549: @tex
        !           550: \global\baselineskip 11.5pt
        !           551: @end tex
        !           552: 
        !           553: @iftex
        !           554: @unnumberedsec TERMS AND CONDITIONS
        !           555: @end iftex
        !           556: @ifinfo
        !           557: @center TERMS AND CONDITIONS
        !           558: @end ifinfo
        !           559: 
        !           560: @enumerate
        !           561: @item
        !           562: This License Agreement applies to any program or other work which
        !           563: contains a notice placed by the copyright holder saying it may be
        !           564: distributed under the terms of this General Public License.  The
        !           565: ``Program'', below, refers to any such program or work, and a ``work based
        !           566: on the Program'' means either the Program or any work containing the
        !           567: Program or a portion of it, either verbatim or with modifications.  Each
        !           568: licensee is addressed as ``you''.
        !           569: 
        !           570: @item
        !           571: @cindex Distribution
        !           572: You may copy and distribute verbatim copies of the Program's source
        !           573: code as you receive it, in any medium, provided that you conspicuously and
        !           574: appropriately publish on each copy an appropriate copyright notice and
        !           575: disclaimer of warranty; keep intact all the notices that refer to this
        !           576: General Public License and to the absence of any warranty; and give any
        !           577: other recipients of the Program a copy of this General Public License
        !           578: along with the Program.  You may charge a fee for the physical act of
        !           579: transferring a copy.
        !           580: 
        !           581: @item
        !           582: You may modify your copy or copies of the Program or any portion of
        !           583: it, and copy and distribute such modifications under the terms of Paragraph
        !           584: 1 above, provided that you also do the following:
        !           585: 
        !           586: @itemize @bullet
        !           587: @item
        !           588: cause the modified files to carry prominent notices stating that
        !           589: you changed the files and the date of any change; and
        !           590: 
        !           591: @item
        !           592: cause the whole of any work that you distribute or publish, that
        !           593: in whole or in part contains the Program or any part thereof, either
        !           594: with or without modifications, to be licensed at no charge to all
        !           595: third parties under the terms of this General Public License (except
        !           596: that you may choose to grant warranty protection to some or all
        !           597: third parties, at your option).
        !           598: 
        !           599: @item
        !           600: If the modified program normally reads commands interactively when
        !           601: run, you must cause it, when started running for such interactive use
        !           602: in the simplest and most usual way, to print or display an
        !           603: announcement including an appropriate copyright notice and a notice
        !           604: that there is no warranty (or else, saying that you provide a
        !           605: warranty) and that users may redistribute the program under these
        !           606: conditions, and telling the user how to view a copy of this General
        !           607: Public License.
        !           608: 
        !           609: @item
        !           610: You may charge a fee for the physical act of transferring a
        !           611: copy, and you may at your option offer warranty protection in
        !           612: exchange for a fee.
        !           613: @end itemize
        !           614: 
        !           615: Mere aggregation of another independent work with the Program (or its
        !           616: derivative) on a volume of a storage or distribution medium does not bring
        !           617: the other work under the scope of these terms.
        !           618: 
        !           619: @item
        !           620: You may copy and distribute the Program (or a portion or derivative of
        !           621: it, under Paragraph 2) in object code or executable form under the terms of
        !           622: Paragraphs 1 and 2 above provided that you also do one of the following:
        !           623: 
        !           624: @itemize @bullet
        !           625: @item
        !           626: accompany it with the complete corresponding machine-readable
        !           627: source code, which must be distributed under the terms of
        !           628: Paragraphs 1 and 2 above; or,
        !           629: 
        !           630: @item
        !           631: accompany it with a written offer, valid for at least three
        !           632: years, to give any third party free (except for a nominal charge
        !           633: for the cost of distribution) a complete machine-readable copy of the
        !           634: corresponding source code, to be distributed under the terms of
        !           635: Paragraphs 1 and 2 above; or,
        !           636: 
        !           637: @item
        !           638: accompany it with the information you received as to where the
        !           639: corresponding source code may be obtained.  (This alternative is
        !           640: allowed only for noncommercial distribution and only if you
        !           641: received the program in object code or executable form alone.)
        !           642: @end itemize
        !           643: 
        !           644: Source code for a work means the preferred form of the work for making
        !           645: modifications to it.  For an executable file, complete source code means
        !           646: all the source code for all modules it contains; but, as a special
        !           647: exception, it need not include source code for modules which are standard
        !           648: libraries that accompany the operating system on which the executable
        !           649: file runs, or for standard header files or definitions files that
        !           650: accompany that operating system.
        !           651: 
        !           652: @item
        !           653: You may not copy, modify, sublicense, distribute or transfer the
        !           654: Program except as expressly provided under this General Public License.
        !           655: Any attempt otherwise to copy, modify, sublicense, distribute or transfer
        !           656: the Program is void, and will automatically terminate your rights to use
        !           657: the Program under this License.  However, parties who have received
        !           658: copies, or rights to use copies, from you under this General Public
        !           659: License will not have their licenses terminated so long as such parties
        !           660: remain in full compliance.
        !           661: 
        !           662: @item
        !           663: By copying, distributing or modifying the Program (or any work based
        !           664: on the Program) you indicate your acceptance of this license to do so,
        !           665: and all its terms and conditions.
        !           666: 
        !           667: @item
        !           668: Each time you redistribute the Program (or any work based on the
        !           669: Program), the recipient automatically receives a license from the original
        !           670: licensor to copy, distribute or modify the Program subject to these
        !           671: terms and conditions.  You may not impose any further restrictions on the
        !           672: recipients' exercise of the rights granted herein.
        !           673: 
        !           674: @item
        !           675: The Free Software Foundation may publish revised and/or new versions
        !           676: of the General Public License from time to time.  Such new versions will
        !           677: be similar in spirit to the present version, but may differ in detail to
        !           678: address new problems or concerns.
        !           679: 
        !           680: Each version is given a distinguishing version number.  If the Program
        !           681: specifies a version number of the license which applies to it and ``any
        !           682: later version'', you have the option of following the terms and conditions
        !           683: either of that version or of any later version published by the Free
        !           684: Software Foundation.  If the Program does not specify a version number of
        !           685: the license, you may choose any version ever published by the Free Software
        !           686: Foundation.
        !           687: 
        !           688: @item
        !           689: If you wish to incorporate parts of the Program into other free
        !           690: programs whose distribution conditions are different, write to the author
        !           691: to ask for permission.  For software which is copyrighted by the Free
        !           692: Software Foundation, write to the Free Software Foundation; we sometimes
        !           693: make exceptions for this.  Our decision will be guided by the two goals
        !           694: of preserving the free status of all derivatives of our free software and
        !           695: of promoting the sharing and reuse of software generally.
        !           696: 
        !           697: @iftex
        !           698: @heading NO WARRANTY
        !           699: @end iftex
        !           700: @ifinfo
        !           701: @center NO WARRANTY
        !           702: @end ifinfo
        !           703: 
        !           704: @item
        !           705: BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
        !           706: FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
        !           707: OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
        !           708: PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
        !           709: OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
        !           710: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
        !           711: TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
        !           712: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
        !           713: REPAIR OR CORRECTION.
        !           714: 
        !           715: @item
        !           716: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
        !           717: ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
        !           718: REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
        !           719: INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
        !           720: ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
        !           721: LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
        !           722: SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
        !           723: WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
        !           724: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
        !           725: @end enumerate
        !           726: 
        !           727: @iftex
        !           728: @heading END OF TERMS AND CONDITIONS
        !           729: @end iftex
        !           730: @ifinfo
        !           731: @center END OF TERMS AND CONDITIONS
        !           732: @end ifinfo
        !           733: 
        !           734: @tex
        !           735: \global\baselineskip 12pt
        !           736: @end tex
        !           737: 
        !           738: @page
        !           739: @unnumberedsec How to Apply These Terms to Your New Programs
        !           740: 
        !           741:   If you develop a new program, and you want it to be of the greatest
        !           742: possible use to humanity, the best way to achieve this is to make it
        !           743: free software which everyone can redistribute and change under these
        !           744: terms.
        !           745: 
        !           746:   To do so, attach the following notices to the program.  It is safest to
        !           747: attach them to the start of each source file to most effectively convey
        !           748: the exclusion of warranty; and each file should have at least the
        !           749: ``copyright'' line and a pointer to where the full notice is found.
        !           750: 
        !           751: @smallexample
        !           752: @var{one line to give the program's name and a brief idea of what it does.}
        !           753: Copyright (C) 19@var{yy}  @var{name of author}
        !           754: 
        !           755: This program is free software; you can redistribute it and/or modify
        !           756: it under the terms of the GNU General Public License as published by
        !           757: the Free Software Foundation; either version 1, or (at your option)
        !           758: any later version.
        !           759: 
        !           760: This program is distributed in the hope that it will be useful,
        !           761: but WITHOUT ANY WARRANTY; without even the implied warranty of
        !           762: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        !           763: GNU General Public License for more details.
        !           764: 
        !           765: You should have received a copy of the GNU General Public License
        !           766: along with this program; if not, write to the Free Software
        !           767: Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
        !           768: @end smallexample
        !           769: 
        !           770: Also add information on how to contact you by electronic and paper mail.
        !           771: 
        !           772: If the program is interactive, make it output a short notice like this
        !           773: when it starts in an interactive mode:
        !           774: 
        !           775: @smallexample
        !           776: Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
        !           777: Gnomovision comes with ABSOLUTELY NO WARRANTY; for details 
        !           778: type `show w'.  This is free software, and you are welcome 
        !           779: to redistribute it under certain conditions; type `show c'
        !           780: for details.
        !           781: @end smallexample
        !           782: 
        !           783: The hypothetical commands `show w' and `show c' should show the
        !           784: appropriate parts of the General Public License.  Of course, the
        !           785: commands you use may be called something other than `show w' and `show
        !           786: c'; they could even be mouse-clicks or menu items---whatever suits your
        !           787: program.
        !           788: 
        !           789: You should also get your employer (if you work as a programmer) or your
        !           790: school, if any, to sign a ``copyright disclaimer'' for the program, if
        !           791: necessary.  Here is a sample; alter the names:
        !           792: 
        !           793: @example
        !           794: Yoyodyne, Inc., hereby disclaims all copyright 
        !           795: interest in the program `Gnomovision'
        !           796: (a program to direct compilers to make passes
        !           797: at assemblers) written by James Hacker.
        !           798: 
        !           799: @group
        !           800: @var{signature of Ty Coon}, 1 April 1989
        !           801: Ty Coon, President of Vice
        !           802: @end group
        !           803: @end example
        !           804: 
        !           805: That's all there is to it!
        !           806: 
        !           807: @node Intro, Glossary, License, Top
        !           808: @unnumbered Introduction
        !           809: 
        !           810:   You are reading about GNU Emacs, the GNU incarnation of the advanced,
        !           811: self-documenting, customizable, extensible real-time display editor Emacs.
        !           812: (The `G' in `GNU' is not silent.)
        !           813: 
        !           814:   We say that Emacs is a @dfn{display} editor because normally the text
        !           815: being edited is visible on the screen and is updated automatically as you
        !           816: type your commands.  @xref{Screen,Display}.
        !           817: 
        !           818:   We call it a @dfn{real-time} editor because the display is updated very
        !           819: frequently, usually after each character or pair of characters you
        !           820: type.  This minimizes the amount of information you must keep in your
        !           821: head as you edit.  @xref{Basic,Real-time,Basic Editing}.
        !           822: 
        !           823:   We call Emacs advanced because it provides facilities that go beyond
        !           824: simple insertion and deletion: filling of text; automatic indentation of
        !           825: programs; viewing two or more files at once; and dealing in terms of
        !           826: characters, words, lines, sentences, paragraphs, and pages, as well as
        !           827: expressions and comments in several different programming languages.  It is
        !           828: much easier to type one command meaning ``go to the end of the paragraph''
        !           829: than to find that spot with simple cursor keys.
        !           830: 
        !           831:   @dfn{Self-documenting} means that at any time you can type a special
        !           832: character, @kbd{Control-h}, to find out what your options are.  You can
        !           833: also use it to find out what any command does, or to find all the commands
        !           834: that pertain to a topic.  @xref{Help}.
        !           835: 
        !           836:   @dfn{Customizable} means that you can change the definitions of Emacs
        !           837: commands in little ways.  For example, if you use a programming language in
        !           838: which comments start with @samp{<**} and end with @samp{**>}, you can tell
        !           839: the Emacs comment manipulation commands to use those strings
        !           840: (@pxref{Comments}).  Another sort of customization is rearrangement of the
        !           841: command set.  For example, if you prefer the four basic cursor motion
        !           842: commands (up, down, left and right) on keys in a diamond pattern on the
        !           843: keyboard, you can have it.  @xref{Customization}.
        !           844: 
        !           845:   @dfn{Extensible} means that you can go beyond simple customization and
        !           846: write entirely new commands, programs in the Lisp language to be run by
        !           847: Emacs's own Lisp interpreter.  Emacs is an ``on-line extensible'' system,
        !           848: which means that it is divided into many functions that call each other,
        !           849: any of which can be redefined in the middle of an editing session.  Any
        !           850: part of Emacs can be replaced without making a separate copy of all of
        !           851: Emacs.  Most of the editing commands of Emacs are written in Lisp already;
        !           852: the few exceptions could have been written in Lisp but are written in C for
        !           853: efficiency.  Although only a programmer can write an extension, anybody can
        !           854: use it afterward.
        !           855: 
        !           856: @node Screen, Characters, Concept Index, Top
        !           857: @chapter The Organization of the Screen
        !           858: @cindex screen
        !           859: 
        !           860:   Emacs divides the screen into several areas, each of which contains
        !           861: its own sorts of information.  The biggest area, of course, is the one
        !           862: in which you usually see the text you are editing.
        !           863: 
        !           864:   When you are using Emacs, the screen is divided into a number of
        !           865: @dfn{windows}.  Initially there is one text window occupying all but the
        !           866: last line, plus the special @dfn{echo area} or @dfn{minibuffer window} in
        !           867: the last line.  The text window can be subdivided horizontally or
        !           868: vertically into multiple text windows, each of which can be used for a
        !           869: different file (@pxref{Windows}).  The window that the cursor is in is the
        !           870: @dfn{selected window}, in which editing takes place.  The other windows are
        !           871: just for reference unless you select one of them.
        !           872: 
        !           873:   Each text window's last line is a @dfn{mode line} which describes what is
        !           874: going on in that window.  It is in inverse video if the terminal supports
        !           875: that, and contains text that starts like @samp{-----Emacs:@: @var{something}}.  Its
        !           876: purpose is to indicate what buffer is being displayed above it in the
        !           877: window; what major and minor modes are in use; and whether the buffer's
        !           878: text has been changed.
        !           879: 
        !           880: @menu
        !           881: * Point::      The place in the text where editing commands operate.
        !           882: * Echo Area::   Short messages appear at the bottom of the screen.
        !           883: * Mode Line::  Interpreting the mode line.
        !           884: @end menu
        !           885: 
        !           886: @node Point, Echo Area, Screen, Screen
        !           887: @section Point
        !           888: @cindex point
        !           889: @cindex cursor
        !           890: 
        !           891:   When Emacs is running, the terminal's cursor shows the location at
        !           892: which editing commands will take effect.  This location is called
        !           893: @dfn{point}.  Other commands move point through the text, so that you
        !           894: can edit at different places in it.
        !           895: 
        !           896:   While the cursor appears to point @var{at} a character, point should be
        !           897: thought of as @var{between} two characters; it points @var{before} the character
        !           898: that the cursor appears on top of.  Sometimes people speak of ``the
        !           899: cursor'' when they mean ``point'', or speak of commands that move point as
        !           900: ``cursor motion'' commands.
        !           901: 
        !           902:   Terminals have only one cursor, and when output is in progress it must
        !           903: appear where the typing is being done.  This does not mean that point is
        !           904: moving.  It is only that Emacs has no way to show you the location of point
        !           905: except when the terminal is idle.
        !           906: 
        !           907:   If you are editing several files in Emacs, each file has its own point
        !           908: location.  A file that is not being displayed remembers where point is so
        !           909: that it can be seen when you look at that file again.
        !           910: 
        !           911:   When there are multiple text windows, each window has its own point
        !           912: location.  The cursor shows the location of point in the selected window.
        !           913: This also is how you can tell which window is selected.  If the same buffer
        !           914: appears in more than one window, point can be moved in each window
        !           915: independently.
        !           916: 
        !           917:   The term `point' comes from the character @samp{.}, which was the
        !           918: command in @sc{teco} (the language in which the original Emacs was written)
        !           919: for accessing the value now called `point'.
        !           920: 
        !           921: @node Echo Area, Mode Line, Point, Screen
        !           922: @section The Echo Area
        !           923: @cindex echo area
        !           924: 
        !           925:   The line at the bottom of the screen (below the mode line) is the
        !           926: @dfn{echo area}.  It is used to display small amounts of text for several
        !           927: purposes.
        !           928: 
        !           929:   @dfn{Echoing} means printing out the characters that you type.  Emacs
        !           930: never echoes single-character commands, and multi-character commands are
        !           931: echoed only if you pause while typing them.  As soon as you pause for more
        !           932: than a second in the middle of a command, all the characters of the command
        !           933: so far are echoed.  This is intended to @dfn{prompt} you for the rest of
        !           934: the command.  Once echoing has started, the rest of the command is echoed
        !           935: immediately when you type it.  This behavior is designed to give confident
        !           936: users fast response, while giving hesitant users maximum feedback.  You
        !           937: can change this behavior by setting a variable (@pxref{Display Vars}).
        !           938: 
        !           939:   If a command cannot be executed, it may print an @dfn{error message} in
        !           940: the echo area.  Error messages are accompanied by a beep or by flashing the
        !           941: screen.  Also, any input you have typed ahead is thrown away when an error
        !           942: happens.
        !           943: 
        !           944:   Some commands print informative messages in the echo area.  These
        !           945: messages look much like error messages, but they are not announced with a
        !           946: beep and do not throw away input.  Sometimes the message tells you what the
        !           947: command has done, when this is not obvious from looking at the text being
        !           948: edited.  Sometimes the sole purpose of a command is to print a message
        !           949: giving you specific information.  For example, the command @kbd{C-x =} is
        !           950: used to print a message describing the character position of point in the
        !           951: text and its current column in the window.  Commands that take a long time
        !           952: often display messages ending in @samp{...} while they are working, and
        !           953: add @samp{done} at the end when they are finished.
        !           954: 
        !           955:   The echo area is also used to display the @dfn{minibuffer}, a window that
        !           956: is used for reading arguments to commands, such as the name of a file to be
        !           957: edited.  When the minibuffer is in use, the echo area begins with a prompt
        !           958: string that usually ends with a colon; also, the cursor appears in that line
        !           959: because it is the selected window.  You can always get out of the
        !           960: minibuffer by typing @kbd{C-g}.  @xref{Minibuffer}.
        !           961: 
        !           962: @node Mode Line,, Echo Area, Screen
        !           963: @section The Mode Line
        !           964: @cindex mode line
        !           965: @cindex top level
        !           966: 
        !           967:   Each text window's last line is a @dfn{mode line} which describes what is
        !           968: going on in that window.  When there is only one text window, the mode line
        !           969: appears right above the echo area.  The mode line is in inverse video if
        !           970: the terminal supports that, starts and ends with dashes, and contains text
        !           971: like @samp{Emacs:@: @var{something}}.
        !           972: 
        !           973:   If a mode line has something else in place of @samp{Emacs:@: @var{something}},
        !           974: then the window above it is in a special subsystem such as Dired.  The mode
        !           975: line then indicates the status of the subsystem.
        !           976: 
        !           977:   Normally, the mode line has the following appearance:
        !           978: 
        !           979: @example
        !           980: --@var{ch}-Emacs: @var{buf}      (@var{major} @var{minor})----@var{pos}------
        !           981: @end example
        !           982: 
        !           983: @noindent
        !           984: This gives information about the buffer being displayed in the window: the
        !           985: buffer's name, what major and minor modes are in use, whether the buffer's
        !           986: text has been changed, and how far down the buffer you are currently
        !           987: looking.
        !           988: 
        !           989:   @var{ch} contains two stars @samp{**} if the text in the buffer has been
        !           990: edited (the buffer is ``modified''), or @samp{--} if the buffer has not been
        !           991: edited.  Exception: for a read-only buffer, it is @samp{%%}.
        !           992: 
        !           993:   @var{buf} is the name of the window's chosen @dfn{buffer}.  The chosen buffer
        !           994: in the selected window (the window that the cursor is in) is also Emacs's
        !           995: selected buffer, the one that editing takes place in.  When we speak of
        !           996: what some command does to ``the buffer'', we are talking about the
        !           997: currently selected buffer.  @xref{Buffers}.
        !           998: 
        !           999:   @var{pos} tells you whether there is additional text above the top of the
        !          1000: screen, or below the bottom.  If your file is small and it is all on the
        !          1001: screen, @var{pos} is @samp{All}.  Otherwise, it is @samp{Top} if you are
        !          1002: looking at the beginning of the file, @samp{Bot} if you are looking at the
        !          1003: end of the file, or @samp{@var{nn}%}, where @var{nn} is the percentage of
        !          1004: the file above the top of the screen.@refill
        !          1005: 
        !          1006:   @var{major} is the name of the @dfn{major mode} in effect in the buffer.  At
        !          1007: any time, each buffer is in one and only one of the possible major modes.
        !          1008: The major modes available include Fundamental mode (the least specialized),
        !          1009: Text mode, Lisp mode, and C mode.  @xref{Major Modes}, for details
        !          1010: of how the modes differ and how to select one.@refill
        !          1011: 
        !          1012:   @var{minor} is a list of some of the @dfn{minor modes} that are turned on
        !          1013: at the moment in the window's chosen buffer.  @samp{Fill} means that Auto
        !          1014: Fill mode is on.  @samp{Abbrev} means that Word Abbrev mode is on.
        !          1015: @samp{Ovwrt} means that Overwrite mode is on.  @xref{Minor Modes}, for more
        !          1016: information.  @samp{Narrow} means that the buffer being displayed has
        !          1017: editing restricted to only a portion of its text.  This is not really a
        !          1018: minor mode, but is like one.  @xref{Narrowing}.  @samp{Def} means that a
        !          1019: keyboard macro is being defined.  @xref{Keyboard Macros}.
        !          1020: 
        !          1021:   Some buffers display additional information after the minor modes.  For
        !          1022: example, Rmail buffers display the current message number and the total
        !          1023: number of messages.  Compilation buffers and Shell mode display the status
        !          1024: of the subprocess.
        !          1025: 
        !          1026:   In addition, if Emacs is currently inside a recursive editing level,
        !          1027: square brackets (@samp{[@dots{}]}) appear around the parentheses that
        !          1028: surround the modes.  If Emacs is in one recursive editing level within
        !          1029: another, double square brackets appear, and so on.  Since this information
        !          1030: pertains to Emacs in general and not to any one buffer, the square brackets
        !          1031: appear in every mode line on the screen or not in any of them.
        !          1032: @xref{Recursive Edit}.@refill
        !          1033: 
        !          1034: @cindex display time
        !          1035: @cindex time displayed in mode line
        !          1036: @findex display-time
        !          1037:   Emacs can optionally display the time and system load in all mode lines.
        !          1038: To enable this feature, type @kbd{M-x display-time}.  The information added
        !          1039: to the mode line usually appears after the file name, before the mode names
        !          1040: and their parentheses.  It looks like this:
        !          1041: 
        !          1042: @example
        !          1043: @var{hh}:@var{mm}pm @var{l.ll} [@var{d}]
        !          1044: @end example
        !          1045: 
        !          1046: @noindent
        !          1047: (Some fields may be missing if your operating system cannot support them.)
        !          1048: @var{hh} and @var{mm} are the hour and minute, followed always by @samp{am}
        !          1049: or @samp{pm}.  @var{l.ll} is the average number of running processes in the
        !          1050: whole system recently.  @var{d} is an approximate index of the ratio of
        !          1051: disk activity to cpu activity for all users.
        !          1052: 
        !          1053: @cindex mail arrival
        !          1054: The word @samp{Mail} appears after the load level if there is mail for
        !          1055: you that you have not read yet.
        !          1056: 
        !          1057: @vindex mode-line-inverse-video
        !          1058:   Customization note: the user variable @code{mode-line-inverse-video} controls
        !          1059: whether the mode line is displayed in inverse video (assuming the
        !          1060: terminal supports it); @code{nil} means no inverse video.  The default
        !          1061: is @code{t}.
        !          1062: 
        !          1063: @iftex
        !          1064: @chapter Characters, Keys and Commands
        !          1065: 
        !          1066:   This chapter explains the character set used by Emacs for input commands
        !          1067: and for the contents of files, and also explains the concepts of
        !          1068: @dfn{keys} and @dfn{commands} which are necessary for understanding how
        !          1069: your keyboard input is understood by Emacs.
        !          1070: @end iftex
        !          1071: 
        !          1072: @node Characters, Keys, Screen, Top
        !          1073: @section The Emacs Character Set
        !          1074: @cindex character set
        !          1075: @cindex ASCII
        !          1076: 
        !          1077:   GNU Emacs uses the @sc{ascii} character set, which defines 128 different
        !          1078: character codes.  Some of these codes are assigned graphic symbols such
        !          1079: as @samp{a} and @samp{=}; the rest are control characters, such as
        !          1080: @kbd{Control-a} (also called @kbd{C-a} for short).  @kbd{C-a} gets its name
        !          1081: from the fact that you type it by holding down the @key{CTRL} key and
        !          1082: then pressing @kbd{a}.  There is no distinction between @kbd{C-a} and
        !          1083: @kbd{C-A}; they are the same character.@refill
        !          1084: 
        !          1085:   Some control characters have special names, and special keys you can
        !          1086: type them with: @key{RET}, @key{TAB}, @key{LFD}, @key{DEL} and @key{ESC}.
        !          1087: The space character is usually referred to below as @key{SPC}, even though
        !          1088: strictly speaking it is a graphic character whose graphic happens to be
        !          1089: blank.@refill
        !          1090: 
        !          1091:   Emacs extends the 7-bit @sc{ascii} code to an 8-bit code by adding an extra
        !          1092: bit to each character.  This makes 256 possible command characters.  The
        !          1093: additional bit is called Meta.  Any @sc{ascii} character can be made Meta;
        !          1094: examples of Meta characters include @kbd{Meta-a} (@kbd{M-a}, for short),
        !          1095: @kbd{M-A} (not the same character as @kbd{M-a}, but those two characters
        !          1096: normally have the same meaning in Emacs), @kbd{M-@key{RET}}, and
        !          1097: @kbd{M-C-a}.  For traditional reasons, @kbd{M-C-a} is usually called
        !          1098: @kbd{C-M-a}; logically speaking, the order in which the modifier keys
        !          1099: @key{CTRL} and @key{META} are mentioned does not matter.@refill
        !          1100: 
        !          1101: @cindex Control
        !          1102: @cindex Meta
        !          1103: @cindex C-
        !          1104: @cindex M-
        !          1105: @cindex ESC replacing META key
        !          1106:   Some terminals have a @key{META} key, and allow you to type Meta
        !          1107: characters by holding this key down.  Thus, @kbd{Meta-a} is typed by
        !          1108: holding down @key{META} and pressing @kbd{a}.  The @key{META} key works
        !          1109: much like the @key{SHIFT} key.  Such a key is not always labeled
        !          1110: @key{META}, however, as this function is often a special option for a key
        !          1111: with some other primary purpose.@refill
        !          1112: 
        !          1113:   If there is no @key{META} key, you
        !          1114: can still type Meta characters using two-character sequences starting with
        !          1115: @key{ESC}.  Thus, to enter @kbd{M-a}, you could type @kbd{@key{ESC} a}.  To
        !          1116: enter @kbd{C-M-a}, you would type @kbd{@key{ESC} C-a}.  @key{ESC} is
        !          1117: allowed on terminals with Meta keys, too, in case you have formed a habit
        !          1118: of using it.@refill
        !          1119: 
        !          1120: @vindex meta-flag
        !          1121:   Emacs believes the terminal has a @key{META} key if the variable
        !          1122: @code{meta-flag} is non-@code{nil}.  Normally this is set automatically
        !          1123: according to the termcap entry for your terminal type.  However, sometimes
        !          1124: the termcap entry is wrong, and then it is useful to set this variable
        !          1125: yourself.  @xref{Variables}, for how to do this.
        !          1126: 
        !          1127:   Emacs buffers also use an 8-bit character set, because bytes have 8 bits,
        !          1128: but only the @sc{ascii} characters are considered meaningful.
        !          1129: @sc{ascii} graphic characters in Emacs buffers are displayed with
        !          1130: their graphics.  @key{LFD} is the same as a newline character; it is
        !          1131: displayed by starting a new line.  @key{TAB} is displayed by moving to
        !          1132: the next tab stop column (usually every 8 columns).  Other control
        !          1133: characters are displayed as a caret (@samp{^}) followed by the
        !          1134: non-control version of the character; thus, @kbd{C-a} is displayed as
        !          1135: @samp{^A}.  Non-@sc{ascii} characters 128 and up are displayed with octal
        !          1136: escape sequences; thus, character code 243 (octal), also called
        !          1137: @kbd{M-#} when used as an input character, is displayed as
        !          1138: @samp{\243}.
        !          1139: @c !! need glossary definition of octal escape sequence
        !          1140: 
        !          1141: @node Keys, Commands, Characters, Top
        !          1142: @section Keys
        !          1143: 
        !          1144: @cindex key
        !          1145: @cindex prefix key
        !          1146:   A @dfn{complete key}---where `key' is short for @dfn{key sequence}---is a
        !          1147: sequence of keystrokes that are understood by Emacs as a unit, as a single
        !          1148: command (possibly undefined).  Most single characters constitute complete
        !          1149: keys in the standard Emacs command set; there are also some multi-character
        !          1150: keys.  Examples of complete keys are @kbd{C-a}, @kbd{X}, @key{RET},
        !          1151: @kbd{C-x C-f} and @kbd{C-x 4 C-f}.@refill
        !          1152: 
        !          1153: @kindex C-c
        !          1154: @kindex C-x
        !          1155: @kindex C-h
        !          1156: @kindex ESC
        !          1157:   A @dfn{prefix key} is a sequence of keystrokes that are the beginning of
        !          1158: a complete key, but not a whole one.  Prefix keys and complete keys are
        !          1159: collectively called @dfn{keys}.
        !          1160: 
        !          1161:   A prefix key is the beginning of a series of longer sequences that are
        !          1162: valid keys; adding any single character to the end of the prefix gives a
        !          1163: valid key, which could be defined as an Emacs command, or could be a prefix
        !          1164: itself.  For example, @kbd{C-x} is standardly defined as a prefix, so
        !          1165: @kbd{C-x} and the next input character combine to make a two-character key.
        !          1166: There are 256 different two-character keys starting with @kbd{C-x}, one for
        !          1167: each possible second character.  Many of these two-character keys starting
        !          1168: with @kbd{C-x} are standardly defined as Emacs commands.  Notable examples
        !          1169: include @kbd{C-x C-f} and @kbd{C-x s} (@pxref{Files}).
        !          1170: 
        !          1171:   Adding one character to a prefix key does not have to form a complete
        !          1172: key.  It could make another, longer prefix.  For example, @kbd{C-x 4} is
        !          1173: itself a prefix that leads to 256 different three-character keys, including
        !          1174: @kbd{C-x 4 f}, @w{@kbd{C-x 4 b}} and so on.  It would be possible to define one
        !          1175: of those three-character sequences as a prefix, creating a series of
        !          1176: four-character keys, but we did not define any of them this way.
        !          1177: 
        !          1178:   By contrast, the two-character sequence @kbd{C-f C-k} is not a key,
        !          1179: because the @kbd{C-f} is a complete key in itself.  It's impossible to give
        !          1180: @kbd{C-f C-k} an independent meaning as a command as long as @kbd{C-f}
        !          1181: retains its meaning.  @kbd{C-f C-k} is two commands.@refill
        !          1182: 
        !          1183:   All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-x}, @kbd{C-h},
        !          1184: @kbd{C-x 4}, and @key{ESC}.  But this is not built in; it is just a matter
        !          1185: of Emacs's standard key bindings.  In customizing Emacs, you could make
        !          1186: new prefix keys, or eliminate these.  @xref{Key Bindings}.@refill
        !          1187: 
        !          1188:   Whether a sequence is a key can be changed by customization.  For
        !          1189: example, if you redefine @kbd{C-f} as a prefix, @kbd{C-f C-k} automatically
        !          1190: becomes a key (complete, unless you define it too as a prefix).
        !          1191: Conversely, if you remove the prefix definition of @kbd{C-x 4}, then
        !          1192: @kbd{C-x 4 f} (or @kbd{C-x 4 @var{anything}}) is no longer a key.
        !          1193: 
        !          1194: @node Commands, Entering Emacs, Keys, Top
        !          1195: @section Keys and Commands
        !          1196: 
        !          1197: @cindex binding
        !          1198: @cindex customization
        !          1199: @cindex keymap
        !          1200: @cindex function
        !          1201: @cindex command
        !          1202:   This manual is full of passages that tell you what particular keys do.
        !          1203: But Emacs does not assign meanings to keys directly.  Instead, Emacs
        !          1204: assigns meanings to @dfn{functions}, and then gives keys their meanings by
        !          1205: @dfn{binding} them to functions.
        !          1206: 
        !          1207:   A function is a Lisp object that can be executed as a program.  Usually
        !          1208: it is a Lisp symbol which has been given a function definition; every
        !          1209: symbol has a name, usually made of a few English words separated by
        !          1210: dashes, such as @code{next-line} or @code{forward-word}.  It also has a
        !          1211: @dfn{definition} which is a Lisp program; this is what makes the
        !          1212: function do what it does.  Only some functions can be the bindings of
        !          1213: keys; these are functions whose definitions use @code{interactive} to
        !          1214: specify how to call them interactively.  Such functions are called
        !          1215: @dfn{commands}, and their names are @dfn{command names}.  
        !          1216: @xref{Defining Commands, , Defining Commands, elisp, The GNU Emacs Lisp
        !          1217: Manual}, for more information.
        !          1218: 
        !          1219:   The bindings between keys and functions are recorded in various tables
        !          1220: called @dfn{keymaps}.  @xref{Keymaps}.
        !          1221: 
        !          1222:   When we say that ``@kbd{C-n} moves down vertically one line'' we are
        !          1223: glossing over a distinction that is irrelevant in ordinary use but is vital
        !          1224: in understanding how to customize Emacs.  It is the function
        !          1225: @code{next-line} that is programmed to move down vertically.  @kbd{C-n} has
        !          1226: this effect @i{because} it is bound to that function.  If you rebind
        !          1227: @kbd{C-n} to the function @code{forward-word} then @kbd{C-n} will move
        !          1228: forward by words instead.  Rebinding keys is a common method of
        !          1229: customization.@refill
        !          1230: 
        !          1231:   In the rest of this manual, we usually ignore this subtlety to keep
        !          1232: things simple.  To give the customizer the information he needs, we
        !          1233: state the name of the command which really does the work in parentheses
        !          1234: after mentioning the key that runs it.  For example, we will say that
        !          1235: ``The command @kbd{C-n} (@code{next-line}) moves point vertically down,''
        !          1236: meaning that @code{next-line} is a command that moves vertically down
        !          1237: and @kbd{C-n} is a key that is standardly bound to it.
        !          1238: 
        !          1239:   While we are on the subject of information for customization only, it's a
        !          1240: good time to tell you about @dfn{variables}.  Often the description of a
        !          1241: command will say, ``To change this, set the variable @code{mumble-foo}.''
        !          1242: A variable is a name used to remember a value.  Most of the variables
        !          1243: documented in this manual exist just to facilitate customization: some
        !          1244: command or other part of Emacs examines the variable and behaves
        !          1245: differently accordingly.  Until you are interested in customizing, you can
        !          1246: ignore the information about variables.  When you are ready to be
        !          1247: interested, read the basic information on variables, and then the
        !          1248: information on individual variables will make sense.  @xref{Variables}.
        !          1249: 
        !          1250: @node Entering Emacs, Exiting, Commands, Top
        !          1251: @chapter Entering and Exiting Emacs
        !          1252: @cindex entering Emacs
        !          1253: 
        !          1254:   The usual way to invoke Emacs is just to type @kbd{emacs @key{RET}} at
        !          1255: the shell.  Emacs clears the screen and then displays an initial advisor
        !          1256: message and copyright notice.  You can begin typing Emacs commands
        !          1257: immediately afterward.
        !          1258: 
        !          1259:   Some operating systems insist on discarding all type-ahead when Emacs
        !          1260: starts up; they give Emacs no way to prevent this.  Therefore, it is
        !          1261: wise to wait until Emacs clears the screen before typing your first
        !          1262: editing command.
        !          1263: 
        !          1264: @vindex initial-major-mode
        !          1265:   Before Emacs reads the first command, you have not had a chance to give a
        !          1266: command to specify a file to edit.  But Emacs must always have a current
        !          1267: buffer for editing.  In an attempt to do something useful, Emacs presents a
        !          1268: buffer named @samp{*scratch*} which is in Lisp Interaction mode; you can
        !          1269: use it to type Lisp expressions and evaluate them, or you can ignore that
        !          1270: capability and simply doodle.  (You can specify a different major mode for
        !          1271: this buffer by setting the variable @code{initial-major-mode} in your init
        !          1272: file.  @xref{Init File}.)
        !          1273: 
        !          1274:   It is also possible to specify files to be visited, Lisp files to be
        !          1275: loaded, and functions to be called, by giving Emacs arguments in the
        !          1276: shell command line.  @xref{Command Switches}.
        !          1277: 
        !          1278: @node Exiting, Command Switches, Entering Emacs, Top
        !          1279: @section Exiting Emacs
        !          1280: @cindex exiting
        !          1281: @cindex killing Emacs
        !          1282: @cindex suspending
        !          1283: 
        !          1284:   There are two commands for exiting Emacs because there are two kinds of
        !          1285: exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs.  @dfn{Suspending} means
        !          1286: stopping Emacs temporarily and returning control to its superior (usually
        !          1287: the shell), allowing you to resume editing later in the same Emacs job,
        !          1288: with the same files, same kill ring, same undo history, and so on.  This is
        !          1289: the usual way to exit.  @dfn{Killing} Emacs means destroying the Emacs job.
        !          1290: You can run Emacs again later, but you will get a fresh Emacs; there is no
        !          1291: way to resume the same editing session after it has been killed.
        !          1292: 
        !          1293: @table @kbd
        !          1294: @item C-z
        !          1295: Suspend Emacs (@code{suspend-emacs}).
        !          1296: @item C-x C-c
        !          1297: Kill Emacs (@code{save-buffers-kill-emacs}).
        !          1298: @end table
        !          1299: 
        !          1300: @kindex C-z
        !          1301: @findex suspend-emacs
        !          1302:   To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}).  This takes
        !          1303: you back to the shell from which you invoked Emacs.  You can resume
        !          1304: Emacs with the command @code{%emacs} if you are using the C shell or the
        !          1305: Bourne-Again shell.
        !          1306: 
        !          1307:   On systems that do not permit programs to be suspended, @kbd{C-z} runs an
        !          1308: inferior shell that communicates directly with the terminal, and Emacs
        !          1309: waits until you exit the subshell.  The only way on these systems to get
        !          1310: back to the shell from which Emacs was run (to log out, for example) is to
        !          1311: kill Emacs.  @kbd{C-d} or @code{exit} are typical commands to exit a
        !          1312: subshell.
        !          1313: 
        !          1314: @kindex C-x C-c
        !          1315: @findex save-buffers-kill-emacs
        !          1316:   To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}).  A
        !          1317: two-character key is used for this to make it harder to type.  Unless a
        !          1318: numeric argument is used, this command first offers to save any modified
        !          1319: buffers.  If you do not save them all, it asks for reconfirmation with
        !          1320: @kbd{yes} before killing Emacs, since any changes not saved before that will be
        !          1321: lost forever.  Also, if any subprocesses are still running, @kbd{C-x C-c}
        !          1322: asks for confirmation about them, since killing Emacs will kill the
        !          1323: subprocesses immediately.
        !          1324: 
        !          1325:   In most programs running on Unix, certain characters may instantly
        !          1326: suspend or kill the program.  (In Berkeley Unix these characters are
        !          1327: normally @kbd{C-z} and @kbd{C-c}.)  @b{This Unix feature is turned off
        !          1328: while you are in Emacs.}  The meanings of @kbd{C-z} and @kbd{C-x C-c} as
        !          1329: keys in Emacs were inspired by the standard Berkeley Unix meanings of
        !          1330: @kbd{C-z} and @kbd{C-c}, but that is their only relationship with
        !          1331: Unix.  You could customize these keys to do anything (@pxref{Keymaps}).
        !          1332: 
        !          1333: @node Command Switches, Basic, Exiting, Top
        !          1334: @section Command Line Switches and Arguments
        !          1335: @cindex command line arguments
        !          1336: @cindex arguments (from shell)
        !          1337: 
        !          1338: 
        !          1339:   GNU Emacs supports command line arguments to request various actions
        !          1340: when invoking Emacs.  These are for compatibility with other editors and
        !          1341: for sophisticated activities.  They are not needed for ordinary editing
        !          1342: with Emacs, so new users can skip this section.
        !          1343: 
        !          1344:   You may be used to using command line arguments with other editors
        !          1345: to specify which file to edit.  That's because many other editors are
        !          1346: designed to be started afresh each time you want to edit.  You
        !          1347: edit one file and then exit the editor.  The next time you want to edit
        !          1348: either another file or the same one, you must run the editor again.
        !          1349: With these editors, it makes sense to use a command line argument
        !          1350: to say which file to edit.
        !          1351: 
        !          1352:   The recommended way to use GNU Emacs is to start it only once, just after
        !          1353: you log in, and do all your editing in the same Emacs process.  Each time
        !          1354: you want to edit a different file, you visit it with the existing Emacs,
        !          1355: which eventually comes to have many files in it ready for editing.  Usually
        !          1356: you do not kill the Emacs until you are about to log out.
        !          1357: 
        !          1358:   In the usual style of Emacs use, files are nearly always read by
        !          1359: typing commands to an editor that is already running.  So command line
        !          1360: arguments for specifying a file when the editor is started are seldom
        !          1361: used.
        !          1362: 
        !          1363:   Emacs accepts command-line arguments that specify files to visit,
        !          1364: functions to call, and other activities and operating modes.
        !          1365: 
        !          1366:   The command arguments are processed in the order they appear in the
        !          1367: command argument list; however, certain arguments (the ones in the second
        !          1368: table) must be at the front of the list if they are used.
        !          1369: 
        !          1370:   Here are the arguments allowed:
        !          1371: 
        !          1372: @table @samp
        !          1373: @item @var{file}
        !          1374: Visit @var{file} using @code{find-file}.  @xref{Visiting}.
        !          1375: 
        !          1376: @item +@var{linenum} @var{file}
        !          1377: Visit @var{file} using @code{find-file}, then go to line number
        !          1378: @var{linenum} in it.
        !          1379: 
        !          1380: @item -l @var{file}
        !          1381: @itemx -load @var{file}
        !          1382: Load a file @var{file} of Lisp code with the function @code{load}.
        !          1383: @xref{Lisp Libraries}.
        !          1384: 
        !          1385: @item -f @var{function}
        !          1386: @itemx -funcall @var{function}
        !          1387: Call Lisp function @var{function} with no arguments.
        !          1388: 
        !          1389: @item -i @var{file}
        !          1390: @itemx -insert @var{file}
        !          1391: Insert the contents of @var{file} into the current buffer.
        !          1392: This is like what @kbd{M-x insert-buffer} does; see @ref{Misc File Ops}.
        !          1393: 
        !          1394: @item -kill
        !          1395: Exit from Emacs without asking for confirmation.
        !          1396: @end table
        !          1397: 
        !          1398:   The following switches are recognized only at the beginning of the
        !          1399: command line.  If more than one of them appears, they must appear in the
        !          1400: order that they appear in this table.
        !          1401: 
        !          1402: @table @samp
        !          1403: @item -t @var{device}
        !          1404: Use @var{device} as the device for terminal input and output.
        !          1405: 
        !          1406: @item -d @var{display}
        !          1407: When running with the X window system, use the display named
        !          1408: @var{display} to make Emacs's X window.
        !          1409: 
        !          1410: @item -nw
        !          1411: Don't use a window system; display text only, using an ordinary terminal
        !          1412: device.  Thus, if you run an X-capable Emacs in an Xterm with
        !          1413: @samp{emacs -nw}, it displays in the Xterm's own window instead of
        !          1414: making its own.
        !          1415: 
        !          1416: @cindex batch mode
        !          1417: @item -batch
        !          1418: Run Emacs in @dfn{batch mode}, which means that the text being edited is
        !          1419: not displayed and the standard Unix interrupt characters such as @kbd{C-z}
        !          1420: and @kbd{C-c} continue to have their normal effect.  Emacs in batch mode
        !          1421: outputs to @code{stdout} only what would normally be printed in the echo
        !          1422: area under program control.
        !          1423: 
        !          1424: Batch mode is used for running programs written in Emacs Lisp from
        !          1425: shell scripts, makefiles, and so on.  Normally the @samp{-l} switch
        !          1426: or @samp{-f} switch will be used as well, to invoke a Lisp program
        !          1427: to do the batch processing.
        !          1428: 
        !          1429: @samp{-batch} implies @samp{-q} (do not load an init file).  It also
        !          1430: causes Emacs to exit after all command switches have been processed.  In
        !          1431: addition, auto-saving is not done except in buffers for which it has
        !          1432: been explicitly requested.
        !          1433: 
        !          1434: @item -q
        !          1435: @itemx -no-init-file
        !          1436: Do not load your Emacs init file @file{~/.emacs}.
        !          1437: 
        !          1438: @item -u @var{user}
        !          1439: @itemx -user @var{user}
        !          1440: Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
        !          1441: your own.
        !          1442: @end table
        !          1443: 
        !          1444:   With X Windows, you can use these additional options to specify how to
        !          1445: display the window.  Each option has a corresponding resource name (used
        !          1446: with @samp{emacs} unless you specify another name with @samp{-rn
        !          1447: @var{name}}), listed with the option, which lets you specify the same
        !          1448: parameter using the usual X Windows defaulting mechanism.  The
        !          1449: corresponding generic resource name (used with @samp{Emacs}) is usually
        !          1450: made by capitalizing the first letter of the individual resource name,
        !          1451: but in some cases it is a completely different string (which is listed
        !          1452: below).
        !          1453: 
        !          1454: @table @code
        !          1455: @item -rn @var{name}
        !          1456: Use @var{name} instead of @samp{emacs} when looking for X resources.
        !          1457: 
        !          1458: @item -font @var{fontname}
        !          1459: @itemx -fn @var{fontname}
        !          1460: Use font @var{fontname}.@*
        !          1461: (Resource @samp{font}.)
        !          1462: 
        !          1463: @item -wn @var{name}
        !          1464: Name the window @var{name}.@*
        !          1465: (Resource @samp{title}.)
        !          1466: 
        !          1467: @item -i
        !          1468: Use a bitmap icon (showing the kitchen sink)
        !          1469: rather than a textual icon.@*
        !          1470: (Resource @samp{bitmapIcon}.)
        !          1471: 
        !          1472: @item -in @var{name}
        !          1473: Name the icon @var{name}.  (Resource @samp{iconName}; @samp{Title}).
        !          1474: 
        !          1475: @item -geometry @var{coords}
        !          1476: @itemx -w @var{coords}
        !          1477: Specify the shape and optionally the position 
        !          1478: of the Emacs window in the usual X way.@*
        !          1479: (Resource @samp{geometry}.)
        !          1480: 
        !          1481: @item -b @var{width}
        !          1482: Specify that the window border is @var{width} pixels thick.@*
        !          1483: (Resource @samp{borderWidth}.)
        !          1484: 
        !          1485: @item -ib @var{width}
        !          1486: Leave @var{width} blank pixels between the border
        !          1487: and the window contents.@*
        !          1488: (Resource @samp{internalBorder}; @samp{BorderWidth}.)
        !          1489: 
        !          1490: @item -r
        !          1491: Use reverse video.@*
        !          1492: (Resource @samp{reverseVideo}.)
        !          1493: 
        !          1494: @item -fg @var{color}
        !          1495: Use color @var{color} for text in the window.@*
        !          1496: (Resource @samp{foreground}.)
        !          1497: 
        !          1498: @item -bg @var{color}
        !          1499: Use the color @var{color} for the background of the window.@*
        !          1500: (Resource @samp{background}.)
        !          1501: 
        !          1502: @item -bd @var{color}
        !          1503: Use color @var{color} for the window border.@*
        !          1504: (Resource @samp{borderColor}.)
        !          1505: 
        !          1506: @item -cr @var{color}
        !          1507: Specify the color, @var{color}, to use for the cursor.@*
        !          1508: (Resource @samp{cursorColor}; @samp{Foreground}.)
        !          1509: 
        !          1510: @item -ms @var{color}
        !          1511: Use color @var{color} for the mouse cursor.@*
        !          1512: (Resource @samp{pointerColor}; @samp{Foreground}.)
        !          1513: @end table
        !          1514: 
        !          1515: @vindex command-line-args
        !          1516:   The init file can get access to the command line argument values as
        !          1517: the elements of a list in the variable @code{command-line-args}.  (The
        !          1518: arguments in the second table above will already have been processed and
        !          1519: will not be in the list.)  The init file can override the normal
        !          1520: processing of the other arguments by setting this variable.
        !          1521: 
        !          1522:   One way to use command arguments is to visit many files automatically:
        !          1523: 
        !          1524: @example
        !          1525: emacs *.c
        !          1526: @end example
        !          1527: 
        !          1528: @noindent
        !          1529: passes each @code{.c} file as a separate argument to Emacs, so that Emacs
        !          1530: visits each file (@pxref{Visiting}).
        !          1531: 
        !          1532:   Here is an advanced example that assumes you have a Lisp program
        !          1533: file called @file{hack-c-program.el} which, when loaded, performs some
        !          1534: useful operation on current buffer, expected to be a C program.
        !          1535: 
        !          1536: @smallexample
        !          1537: emacs -batch foo.c -l hack-c-program -f save-buffer -kill > log
        !          1538: @end smallexample
        !          1539: 
        !          1540: @noindent
        !          1541: This says to visit @file{foo.c}, load @file{hack-c-program.el} (which
        !          1542: makes changes in the visited file), save @file{foo.c} (note that
        !          1543: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
        !          1544: then exit to the shell that this command was done with.  @samp{-batch}
        !          1545: guarantees there will be no problem redirecting output to @file{log},
        !          1546: because Emacs will not assume that it has a display terminal to work
        !          1547: with.
        !          1548: 
        !          1549: @node Basic, Undo, Command Switches, Top
        !          1550: @chapter Basic Editing Commands
        !          1551: 
        !          1552: @kindex C-h t
        !          1553: @findex help-with-tutorial
        !          1554:   We now give the basics of how to enter text, make corrections, and
        !          1555: save the text in a file.  If this material is new to you, you might
        !          1556: learn it more easily by running the Emacs learn-by-doing tutorial.  To
        !          1557: do this, type @w{@kbd{Control-h t}} (@code{help-with-tutorial}).
        !          1558: 
        !          1559: @section Inserting Text
        !          1560: 
        !          1561: @cindex insertion
        !          1562: @cindex point
        !          1563: @cindex cursor
        !          1564: @cindex graphic characters
        !          1565:   To insert printing characters into the text you are editing, just type
        !          1566: them.  This inserts the character into the buffer at the cursor (that is,
        !          1567: at @dfn{point}; @pxref{Point}).  The cursor moves forward.  Any characters
        !          1568: after the cursor move forward too.  If the text in the buffer is
        !          1569: @samp{FOOBAR}, with the cursor before the @samp{B}, then if you type
        !          1570: @kbd{XX}, you get @samp{FOOXXBAR}, with the cursor still before the
        !          1571: @samp{B}.
        !          1572: 
        !          1573: @kindex DEL
        !          1574: @cindex deletion
        !          1575:    To @dfn{delete} text you have just inserted, use @key{DEL}.  @key{DEL}
        !          1576: deletes the character @var{before} the cursor (not the one that the cursor
        !          1577: is on top of or under; that is the character @var{after} the cursor).  The
        !          1578: cursor and all characters after it move backwards.  Therefore, if you type
        !          1579: a printing character and then type @key{DEL}, they cancel out.
        !          1580: 
        !          1581: @kindex RET
        !          1582: @cindex newline
        !          1583:    To end a line and start typing a new one, type @key{RET}.  This inserts
        !          1584: a newline character in the buffer.  If point is in the middle of a line,
        !          1585: @key{RET} splits the line.  Typing @key{DEL} when the cursor is at the
        !          1586: beginning of a line rubs out the newline before the line, thus joining the
        !          1587: line with the preceding line.
        !          1588: 
        !          1589:   Emacs will split lines automatically when they become too long, if you
        !          1590: turn on a special mode called @dfn{Auto Fill} mode.  @xref{Filling}, for
        !          1591: how to use Auto Fill mode.
        !          1592: 
        !          1593: @findex delete-backward-char
        !          1594: @findex newline
        !          1595: @findex self-insert
        !          1596:   Customization information: @key{DEL} in most modes runs the command named
        !          1597: @code{delete-backward-char}; @key{RET} runs the command @code{newline}, and
        !          1598: self-inserting printing characters run the command @code{self-insert},
        !          1599: which inserts whatever character was typed to invoke it.  Some major modes
        !          1600: rebind @key{DEL} to other commands.
        !          1601: 
        !          1602: @cindex quoting
        !          1603: @kindex C-q
        !          1604: @findex quoted-insert
        !          1605:   Direct insertion works for printing characters and @key{SPC}, but other
        !          1606: characters act as editing commands and do not insert themselves.  If you
        !          1607: need to insert a control character or a character whose code is above 200
        !          1608: octal, you must @dfn{quote} it by typing the character @kbd{control-q}
        !          1609: (@code{quoted-insert}) first.  There are two ways to use @kbd{C-q}:@refill
        !          1610: 
        !          1611: @itemize @bullet
        !          1612: @item
        !          1613: @kbd{Control-q} followed by any non-graphic character (even @kbd{C-g})
        !          1614: inserts that character.
        !          1615: @item
        !          1616: @kbd{Control-q} followed by three octal digits inserts the character
        !          1617: with the specified character code.
        !          1618: @end itemize
        !          1619: 
        !          1620: @noindent
        !          1621: A numeric argument to @kbd{C-q} specifies how many copies of the
        !          1622: quoted character should be inserted (@pxref{Arguments}).
        !          1623: 
        !          1624:   If you prefer to have text characters replace (overwrite) existing
        !          1625: text rather than shove it to the right, you can enable Overwrite mode,
        !          1626: a minor mode.  @xref{Minor Modes}.
        !          1627: 
        !          1628: @section Changing the Location of Point
        !          1629: 
        !          1630:   To do more than insert characters, you have to know how to move
        !          1631: point (@pxref{Point}).  Here are a few of the commands for doing that.
        !          1632: 
        !          1633: @kindex C-a
        !          1634: @kindex C-e
        !          1635: @kindex C-f
        !          1636: @kindex C-b
        !          1637: @kindex C-n
        !          1638: @kindex C-p
        !          1639: @kindex C-l
        !          1640: @kindex C-t
        !          1641: @kindex M->
        !          1642: @kindex M-<
        !          1643: @kindex M-r
        !          1644: @findex beginning-of-line
        !          1645: @findex end-of-line
        !          1646: @findex forward-char
        !          1647: @findex backward-char
        !          1648: @findex next-line
        !          1649: @findex previous-line
        !          1650: @findex recenter
        !          1651: @findex transpose-chars
        !          1652: @findex beginning-of-buffer
        !          1653: @findex end-of-buffer
        !          1654: @findex goto-char
        !          1655: @findex goto-line
        !          1656: @findex move-to-window-line
        !          1657: @table @kbd
        !          1658: @item C-a
        !          1659: Move to the beginning of the line (@code{beginning-of-line}).
        !          1660: @item C-e
        !          1661: Move to the end of the line (@code{end-of-line}).
        !          1662: @item C-f
        !          1663: Move forward one character (@code{forward-char}).
        !          1664: @item C-b
        !          1665: Move backward one character (@code{backward-char}).
        !          1666: @item M-f
        !          1667: Move forward one word (@code{forward-word}).
        !          1668: @item M-b
        !          1669: Move backward one word (@code{backward-word}).
        !          1670: @item C-n
        !          1671: Move down one line, vertically (@code{next-line}).  This command
        !          1672: attempts to keep the horizontal position unchanged, so if you start in
        !          1673: the middle of one line, you end in the middle of the next.  When on
        !          1674: the last line of text, @kbd{C-n} creates a new line and moves onto it.
        !          1675: @item C-p
        !          1676: Move up one line, vertically (@code{previous-line}).
        !          1677: @item C-l
        !          1678: Clear the screen and reprint everything (@code{recenter}).  Text moves
        !          1679: on the screen to bring point to the center of the window.
        !          1680: @item M-r
        !          1681: Move point to left margin on the line halfway down the screen or
        !          1682: window (@code{move-to-window-line}).  Text does not move on the
        !          1683: screen.  A numeric argument says how many screen lines down from the
        !          1684: top of the window (zero for the top).  A negative argument counts from
        !          1685: the bottom (@minus{}1 for the bottom).
        !          1686: @item C-t
        !          1687: Transpose two characters, the ones before and after the cursor
        !          1688: (@code{transpose-chars}).
        !          1689: @item M-<
        !          1690: Move to the top of the buffer (@code{beginning-of-buffer}).  With
        !          1691: numeric argument @var{n}, move to @var{n}/10 of the way from the top.
        !          1692: @xref{Arguments}, for more information on numeric arguments.@refill
        !          1693: @item M->
        !          1694: Move to the end of the buffer (@code{end-of-buffer}).
        !          1695: @item M-x goto-char
        !          1696: Read a number @var{n} and move cursor to character number @var{n}.
        !          1697: Position 1 is the beginning of the buffer.
        !          1698: @item M-x goto-line
        !          1699: Read a number @var{n} and move cursor to line number @var{n}.  Line 1
        !          1700: is the beginning of the buffer.
        !          1701: @item C-x C-n
        !          1702: @findex set-goal-column
        !          1703: @cindex goal column
        !          1704: Use the current column of point as the @dfn{semipermanent goal column} for
        !          1705: @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}).  Henceforth, those
        !          1706: commands always move to this column in each line moved into, or as
        !          1707: close as possible given the contents of the line.  This goal column remains
        !          1708: in effect until canceled.
        !          1709: @item C-u C-x C-n
        !          1710: Cancel the goal column.  Henceforth, @kbd{C-n} and @kbd{C-p} once
        !          1711: again try to avoid changing the horizontal position, as usual.
        !          1712: @end table
        !          1713: 
        !          1714: @vindex track-eol
        !          1715:   If you set the variable @code{track-eol} to a non-@code{nil} value, then
        !          1716: @kbd{C-n} and @kbd{C-p} when at the end of the starting line move to the
        !          1717: end of the line.  Normally, @code{track-eol} is @code{nil}.
        !          1718: 
        !          1719: @section Erasing Text
        !          1720: 
        !          1721: @table @kbd
        !          1722: @item @key{DEL}
        !          1723: Delete the character before the cursor (@code{delete-backward-char}).
        !          1724: @item C-d
        !          1725: Delete the character after the cursor (@code{delete-char}).
        !          1726: @item C-k
        !          1727: Kill to the end of the line (@code{kill-line}).
        !          1728: @item M-d
        !          1729: Kill forward to the end of the next word (@code{kill-word}).
        !          1730: @item M-@key{DEL}
        !          1731: Kill back to the beginning of the previous word
        !          1732: (@code{backward-kill-word}).
        !          1733: @end table
        !          1734: 
        !          1735:   You already know about the @key{DEL} key which deletes the character
        !          1736: before the cursor.  Another key, @kbd{Control-d}, deletes the character
        !          1737: after the cursor, causing the rest of the text on the line to shift left.
        !          1738: If @kbd{Control-d} is typed at the end of a line, that line and the next
        !          1739: line are joined together.
        !          1740: 
        !          1741:   To erase a larger amount of text, use the @kbd{Control-k} key, which
        !          1742: kills a line at a time.  If @kbd{C-k} is done at the beginning or middle of
        !          1743: a line, it kills all the text up to the end of the line.  If @kbd{C-k} is
        !          1744: done at the end of a line, it joins that line and the next line.
        !          1745: 
        !          1746:   @xref{Killing}, for more flexible ways of killing text.
        !          1747: 
        !          1748: @section Files
        !          1749: 
        !          1750: @cindex files
        !          1751:   The commands above are sufficient for creating and altering text in an
        !          1752: Emacs buffer; the more advanced Emacs commands just make things easier.
        !          1753: But to keep any text permanently you must put it in a @dfn{file}.  Files
        !          1754: are named units of text which are stored by the operating system for you to
        !          1755: retrieve later by name.  To look at or use the contents of a file in any
        !          1756: way, including editing the file with Emacs, you must specify the file name.
        !          1757: 
        !          1758:   Consider a file named @file{/usr/rms/foo.c}.  In Emacs, to begin editing
        !          1759: this file, type
        !          1760: 
        !          1761: @example
        !          1762: C-x C-f /usr/rms/foo.c @key{RET}
        !          1763: @end example
        !          1764: 
        !          1765: @noindent
        !          1766: Here the file name is given as an @dfn{argument} to the command @kbd{C-x
        !          1767: C-f} (@code{find-file}).  That command uses the @dfn{minibuffer} to
        !          1768: read the argument, and you type @key{RET} to terminate the argument
        !          1769: (@pxref{Minibuffer}).@refill
        !          1770: 
        !          1771:   Emacs obeys the command by @dfn{visiting} the file: creating a buffer,
        !          1772: copying the contents of the file into the buffer, and then displaying the
        !          1773: buffer for you to edit.  You can make changes in it, and then @dfn{save}
        !          1774: the file by typing @kbd{C-x C-s} (@code{save-buffer}).  This makes the
        !          1775: changes permanent by copying the altered contents of the buffer back into
        !          1776: the file @file{/usr/rms/foo.c}.  Until then, the changes are only inside
        !          1777: your Emacs, and the file @file{foo.c} is not changed.@refill
        !          1778: 
        !          1779:   To create a file, just visit the file with @kbd{C-x C-f} as if it already
        !          1780: existed.  Emacs will make an empty buffer in which you can insert the text
        !          1781: you want to put in the file.  When you save your text with @kbd{C-x C-s},
        !          1782: the file will be created.
        !          1783: 
        !          1784:   Of course, there is a lot more to learn about using files.  @xref{Files}.
        !          1785: 
        !          1786: @section Help
        !          1787: 
        !          1788:   If you forget what a key does, you can find out with the Help character,
        !          1789: which is @kbd{C-h}.  Type @kbd{C-h k} followed by the key you want to know
        !          1790: about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n}
        !          1791: does.  @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its
        !          1792: subcommands (the command @code{describe-key}).  The other subcommands of
        !          1793: @kbd{C-h} provide different kinds of help.  Type @kbd{C-h} three times
        !          1794: to get a description of all the help facilities.  @xref{Help}.@refill
        !          1795: 
        !          1796: @menu
        !          1797: * Blank Lines::        Commands to make or delete blank lines.
        !          1798: * Continuation Lines:: Lines too wide for the screen.
        !          1799: * Position Info::      What page, line, row, or column is point on?
        !          1800: * Arguments::         Numeric arguments for repeating a command.
        !          1801: @end menu
        !          1802: 
        !          1803: @page
        !          1804: @node Blank Lines, Continuation Lines, Basic, Basic
        !          1805: @section Blank Lines
        !          1806: 
        !          1807:   Here are special commands and techniques for putting in and taking out
        !          1808: blank lines.
        !          1809: 
        !          1810: @c widecommands
        !          1811: @table @kbd
        !          1812: @item C-o
        !          1813: Insert one or more blank lines after the cursor (@code{open-line}).
        !          1814: @item C-x C-o
        !          1815: Delete all but one of many consecutive blank lines
        !          1816: (@code{delete-blank-lines}).
        !          1817: @end table
        !          1818: 
        !          1819: @kindex C-o
        !          1820: @kindex C-x C-o
        !          1821: @cindex blank lines
        !          1822: @findex open-line
        !          1823: @findex delete-blank-lines
        !          1824:   When you want to insert a new line of text before an existing line, you
        !          1825: can do it by typing the new line of text, followed by @key{RET}.  However,
        !          1826: it may be easier to see what you are doing if you first make a blank line
        !          1827: and then insert the desired text into it.  This is easy to do using the key
        !          1828: @kbd{C-o} (@code{open-line}), which inserts a newline after point but leaves
        !          1829: point in front of the newline.  After @kbd{C-o}, type the text for the new
        !          1830: line.  @kbd{C-o F O O} has the same effect as @w{@kbd{F O O @key{RET}},} except for
        !          1831: the final location of point.
        !          1832: 
        !          1833:   You can make several blank lines by typing @kbd{C-o} several times, or by
        !          1834: giving it an argument to tell it how many blank lines to make.
        !          1835: @xref{Arguments}, for how.
        !          1836: 
        !          1837:   If you have many blank lines in a row and want to get rid of them, use
        !          1838: @kbd{C-x C-o} (@code{delete-blank-lines}).  When point is on a blank line which
        !          1839: is adjacent to at least one other blank line, @kbd{C-x C-o} deletes all but
        !          1840: one of the consecutive blank lines, leaving exactly one.  With point on a
        !          1841: blank line with no other blank line adjacent to it, the sole blank line is
        !          1842: deleted, leaving none.  When point is on a nonblank line, @kbd{C-x C-o}
        !          1843: deletes any blank lines following that nonblank line.
        !          1844: 
        !          1845: @node Continuation Lines, Position Info, Blank Lines, Basic
        !          1846: @section Continuation Lines
        !          1847: 
        !          1848: @cindex continuation line
        !          1849:   If you add too many characters to one line, without breaking it with a
        !          1850: @key{RET}, the line will grow to occupy two (or more) lines on the screen,
        !          1851: with a @samp{\} at the extreme right margin of all but the last of them.
        !          1852: The @samp{\} says that the following screen line is not really a distinct
        !          1853: line in the text, but just the @dfn{continuation} of a line too long to fit
        !          1854: the screen.  Sometimes it is nice to have Emacs insert newlines
        !          1855: automatically when a line gets too long; for this, use Auto Fill mode
        !          1856: (@pxref{Filling}).
        !          1857: 
        !          1858: @vindex truncate-lines
        !          1859: @cindex truncation
        !          1860:   Instead of continuation, long lines can be displayed by @dfn{truncation}.
        !          1861: This means that all the characters that do not fit in the width of the
        !          1862: screen or window do not appear at all.  They remain in the buffer,
        !          1863: temporarily invisible.  @samp{$} is used in the last column instead of
        !          1864: @samp{\} to inform you that truncation is in effect.
        !          1865: 
        !          1866:   Continuation can be turned off for a particular buffer by setting the
        !          1867: variable @code{truncate-lines} to non-@code{nil} in that buffer.
        !          1868: Truncation instead of continuation also happens whenever horizontal
        !          1869: scrolling is in use, and optionally whenever side-by-side windows are in
        !          1870: use (@pxref{Windows}).  Altering the value of @code{truncate-lines} makes
        !          1871: it local to the current buffer; until that time, the default value is in
        !          1872: effect.  The default is initially @code{nil}.  @xref{Locals}.@refill
        !          1873: 
        !          1874: @node Position Info, Arguments, Continuation Lines, Basic
        !          1875: @section Cursor Position Information
        !          1876: 
        !          1877:   If you are accustomed to other display editors, you may be surprised that
        !          1878: Emacs does not always display the page number or line number of point in
        !          1879: the mode line.  This is because the text is stored in a way that makes it
        !          1880: difficult to compute this information.  Displaying them all the time would
        !          1881: be intolerably slow.  They are not needed very often in Emacs anyway,
        !          1882: but there are commands to compute them and print them.
        !          1883: 
        !          1884: @table @kbd
        !          1885: @item M-x what-page
        !          1886: Print page number of point, and line number within page.
        !          1887: @item M-x what-line
        !          1888: Print line number of point in the buffer.
        !          1889: @item M-=
        !          1890: Print number of lines in the current region (@code{count-lines-region}).
        !          1891: @item C-x =
        !          1892: Print character code of character after point, character position of
        !          1893: point, and column of point (@code{what-cursor-position}).
        !          1894: @end table
        !          1895: 
        !          1896: @findex what-page
        !          1897: @findex what-line
        !          1898: @cindex line number
        !          1899:   There are two commands for printing line numbers.  @kbd{M-x what-line}
        !          1900: counts lines from the beginning of the file and prints the line number
        !          1901: point is on.  The first line of the file is line number 1.  These numbers
        !          1902: can be used as arguments to @kbd{M-x goto-line}.  By contrast, @kbd{M-x
        !          1903: what-page} counts pages from the beginning of the file, and counts lines
        !          1904: within the page, printing both of them.  @xref{Pages}.
        !          1905: 
        !          1906: @kindex M-=
        !          1907: @findex count-lines-region
        !          1908:   While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}),
        !          1909: which prints the number of lines in the region (@pxref{Mark}).
        !          1910: @xref{Pages}, for the command @kbd{C-x l} which counts the lines in the
        !          1911: current page.
        !          1912: 
        !          1913: @kindex C-x =
        !          1914: @findex what-cursor-position
        !          1915:   The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out
        !          1916: the column that the cursor is in, and other miscellaneous information about
        !          1917: point.  It prints a line in the echo area that looks like this:
        !          1918: 
        !          1919: @example
        !          1920: Char: x (0170)  point=65986 of 563027(12%)  x=44
        !          1921: @end example
        !          1922: 
        !          1923: @noindent
        !          1924: (In fact, this is the output produced when point is before the @samp{x=44}
        !          1925: in the example.)
        !          1926: 
        !          1927:   The two values after @samp{Char:} describe the character following point,
        !          1928: first by showing it and second by giving its octal character code.
        !          1929: 
        !          1930:   @samp{point=} is followed by the position of point expressed as a character
        !          1931: count.  The front of the buffer counts as position 1, one character later
        !          1932: as 2, and so on.  The next, larger number is the total number of characters
        !          1933: in the buffer.  Afterward in parentheses comes the position expressed as a
        !          1934: percentage of the total size.
        !          1935: 
        !          1936:   @samp{x=} is followed by the horizontal position of point, in columns from the
        !          1937: left edge of the window.
        !          1938: 
        !          1939:   If the buffer has been narrowed, making some of the text at the beginning and
        !          1940: the end temporarily invisible, @kbd{C-x =} prints additional text describing the
        !          1941: current visible range.  For example, it might say
        !          1942: 
        !          1943: @smallexample
        !          1944: Char: x (0170)  point=65986 of 563025(12%) <65102 - 68533>  x=44
        !          1945: @end smallexample
        !          1946: 
        !          1947: @noindent
        !          1948: where the two extra numbers give the smallest and largest character position
        !          1949: that point is allowed to assume.  The characters between those two positions
        !          1950: are the visible ones.  @xref{Narrowing}.
        !          1951: 
        !          1952:   If point is at the end of the buffer (or the end of the visible part),
        !          1953: @kbd{C-x =} omits any description of the character after point.
        !          1954: The output looks like
        !          1955: 
        !          1956: @smallexample
        !          1957: point=563026 of 563025(100%)  x=0
        !          1958: @end smallexample
        !          1959: 
        !          1960: @node Arguments,, Position Info, Basic
        !          1961: @section Numeric Arguments
        !          1962: @cindex numeric arguments
        !          1963: @cindex prefix arguments
        !          1964: @cindex arguments, prefix and numeric
        !          1965: 
        !          1966:   Any Emacs command can be given a @dfn{numeric argument}.  Some commands
        !          1967: interpret the argument as a repetition count.  For example, giving an
        !          1968: argument of ten to the key @kbd{C-f} (the command @code{forward-char}, move
        !          1969: forward one character) moves forward ten characters.  With these commands,
        !          1970: no argument is equivalent to an argument of one.  Negative arguments are
        !          1971: allowed.  Often they tell a command to move or act backwards.
        !          1972: 
        !          1973: @kindex M-1
        !          1974: @kindex M-@t{-}
        !          1975: @findex digit-argument
        !          1976: @findex negative-argument
        !          1977:   If your terminal keyboard has a @key{META} key, the easiest way to
        !          1978: specify a numeric argument is to type digits and/or a minus sign while
        !          1979: holding down the @key{META} key.  For example,
        !          1980: @example
        !          1981: M-5 C-n
        !          1982: @end example
        !          1983: @noindent
        !          1984: would move down five lines.  The characters @kbd{Meta-1}, @kbd{Meta-2}, and
        !          1985: so on, as well as @kbd{Meta--}, do this because they are keys bound to
        !          1986: commands (@code{digit-argument} and @code{negative-argument}) that are
        !          1987: defined to contribute to an argument for the next command.
        !          1988: 
        !          1989: @kindex C-u
        !          1990: @findex universal-argument
        !          1991: @cindex universal argument
        !          1992:   Another way of specifying an argument is to use the @kbd{C-u}
        !          1993: (@code{universal-argument}) command followed by the digits of the argument.
        !          1994: With @kbd{C-u}, you can type the argument digits without holding
        !          1995: down shift keys.  To type a negative argument, start with a minus sign.
        !          1996: Just a minus sign normally means @minus{}1.  @kbd{C-u} works on all terminals.
        !          1997: 
        !          1998:   @kbd{C-u} followed by a character which is neither a digit nor a minus
        !          1999: sign has the special meaning of ``multiply by four''.  It multiplies the
        !          2000: argument for the next command by four.  @kbd{C-u} twice multiplies it by
        !          2001: sixteen.  Thus, @kbd{C-u C-u C-f} moves forward sixteen characters.  This
        !          2002: is a good way to move forward ``fast'', since it moves about 1/5 of a line
        !          2003: in the usual size screen.  Other useful combinations are @kbd{C-u C-n},
        !          2004: @kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u
        !          2005: C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four
        !          2006: lines).@refill
        !          2007: 
        !          2008:   Some commands care only about whether there is an argument, and not about
        !          2009: its value.  For example, the command @kbd{M-q} (@code{fill-paragraph}) with
        !          2010: no argument fills text; with an argument, it justifies the text as well.
        !          2011: (@xref{Filling}, for more information on @kbd{M-q}.)  Just @kbd{C-u} is a
        !          2012: handy way of providing an argument for such commands.
        !          2013: 
        !          2014:   Some commands use the value of the argument as a repeat count, but do
        !          2015: something peculiar when there is no argument.  For example, the command
        !          2016: @kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines,
        !          2017: including their terminating newlines.  But @kbd{C-k} with no argument is
        !          2018: special: it kills the text up to the next newline, or, if point is right at
        !          2019: the end of the line, it kills the newline itself.  Thus, two @kbd{C-k}
        !          2020: commands with no arguments can kill a nonblank line, just like @kbd{C-k}
        !          2021: with an argument of one.  (@xref{Killing}, for more information on
        !          2022: @kbd{C-k}.)@refill
        !          2023: 
        !          2024:   A few commands treat a plain @kbd{C-u} differently from an ordinary
        !          2025: argument.  A few others may treat an argument of just a minus sign
        !          2026: differently from an argument of @minus{}1.  These unusual cases will be
        !          2027: described when they come up; they are always for reasons of convenience
        !          2028: of use of the individual command.
        !          2029: 
        !          2030:   To insert multiple copies of a digit, you can type @kbd{C-u
        !          2031: @var{count} C-u @var{digit}}.  The second @kbd{C-u} ends the numeric
        !          2032: argument, so that the following character always acts a key sequence
        !          2033: to be executed.
        !          2034: 
        !          2035: @c section Autoarg Mode
        !          2036: @ignore
        !          2037: @cindex Autoarg mode
        !          2038:   Users of @sc{ascii} keyboards may prefer to use Autoarg mode.  Autoarg mode
        !          2039: means that you don't need to type C-U to specify a numeric argument.
        !          2040: Instead, you type just the digits.  Digits followed by an ordinary
        !          2041: inserting character are themselves inserted, but digits followed by an
        !          2042: Escape or Control character serve as an argument to it and are not
        !          2043: inserted.  A minus sign can also be part of an argument, but only at the
        !          2044: beginning.  If you type a minus sign following some digits, both the digits
        !          2045: and the minus sign are inserted.
        !          2046: 
        !          2047:   To use Autoarg mode, set the variable @code{autoarg-mode} nonzero.
        !          2048: @xref{Variables}.
        !          2049: 
        !          2050:   Autoargument digits echo at the bottom of the screen; the first nondigit
        !          2051: causes them to be inserted or uses them as an argument.  To insert some
        !          2052: digits and nothing else, you must follow them with a Space and then rub it
        !          2053: out.  C-G cancels the digits, while Delete inserts them all and then rubs
        !          2054: out the last.
        !          2055: @end ignore
        !          2056: 
        !          2057: @node Undo, Minibuffer, Basic, Top
        !          2058: @chapter Undoing Changes
        !          2059: @cindex undo
        !          2060: @cindex mistakes, correcting
        !          2061: 
        !          2062:   Emacs allows all changes made in the text of a buffer to be undone,
        !          2063: up to a certain amount of change (8000 characters).  Each buffer records
        !          2064: changes individually, and the undo command always applies to the
        !          2065: current buffer.  Usually each editing command makes a separate entry
        !          2066: in the undo records, but some commands such as @code{query-replace}
        !          2067: make many entries, and very simple commands such as self-inserting
        !          2068: characters are often grouped to make undoing less tedious.
        !          2069: 
        !          2070: @table @kbd
        !          2071: @item C-x u
        !          2072: Undo one batch of changes (usually, one command worth) (@code{undo}).
        !          2073: @item C-_
        !          2074: The same.
        !          2075: @end table
        !          2076: 
        !          2077: @kindex C-x u
        !          2078: @kindex C-_
        !          2079: @findex undo
        !          2080:   The command @kbd{C-x u} or @kbd{C-_} is how you undo.  The first time you give
        !          2081: this command, it undoes the last change.  Point moves to the text
        !          2082: affected by the undo, so you can see what was undone.
        !          2083: 
        !          2084:   Consecutive repetitions of the @kbd{C-_} or @kbd{C-x u} commands undo earlier
        !          2085: and earlier changes, back to the limit of what has been recorded.  If all
        !          2086: recorded changes have already been undone, the undo command prints an error
        !          2087: message and does nothing.
        !          2088: 
        !          2089:   Any command other than an undo command breaks the sequence of undo
        !          2090: commands.  Starting at this moment, the previous undo commands are
        !          2091: considered ordinary changes that can themselves be undone.  Thus, to
        !          2092: redo changes you have undone, type @kbd{C-f} or any other command that
        !          2093: will have no important effect, and then give more undo commands.
        !          2094: 
        !          2095:   If you notice that a buffer has been modified accidentally, the easiest
        !          2096: way to recover is to type @kbd{C-_} repeatedly until the stars disappear
        !          2097: from the front of the mode line.  At this time, all the modifications you
        !          2098: made have been cancelled.  If you do not remember whether you changed the
        !          2099: buffer deliberately, type @kbd{C-_} once, and when you see the last change
        !          2100: you made undone, you will remember why you made it.  If it was an accident,
        !          2101: leave it undone.  If it was deliberate, redo the change as described in the
        !          2102: preceding paragraph.
        !          2103: 
        !          2104:   Whenever an undo command makes the stars disappear from the mode line,
        !          2105: it means that the buffer contents are the same as they were when the
        !          2106: file was last read in or saved.
        !          2107: 
        !          2108: @findex buffer-enable-undo
        !          2109:   Not all buffers record undo information.  Buffers whose names start with
        !          2110: spaces don't; these buffers are used internally by Emacs and its extensions
        !          2111: to hold text that users don't normally look at or edit.  Also, minibuffers,
        !          2112: help buffers and documentation buffers don't record undo information.
        !          2113: Use the command @code{buffer-enable-undo} to enable recording undo information
        !          2114: in the current buffer.
        !          2115: 
        !          2116:   As editing continues, undo lists get longer and longer.  To prevent
        !          2117: them from using up all available memory space, garbage collection trims
        !          2118: back their sizes to thresholds you can set.  (For this purpose, the
        !          2119: ``size'' of an undo list measures the cons cells that make up the list,
        !          2120: plus the strings of deleted text.)
        !          2121: 
        !          2122: @vindex undo-limit
        !          2123: @vindex undo-strong-limit
        !          2124:   Two variables control the range of acceptable sizes: @code{undo-limit}
        !          2125: and @code{undo-strong-limit}.  Normally, the most recent changes are
        !          2126: kept until their size exceeds @code{undo-limit}; all older changes are
        !          2127: discarded.  But if a change pushes the size above
        !          2128: @code{undo-strong-limit}, it is discarded as well as all older changes.
        !          2129: One exception: the most recent set of changes is sacred; garbage
        !          2130: collection never discards that.  (In Emacs versions 18.57 and 18.58,
        !          2131: these variables are called @code{undo-threshold} and
        !          2132: @code{undo-high-threshold}.)
        !          2133: 
        !          2134:   The reason the @code{undo} command has two keys, @kbd{C-x u} and
        !          2135: @kbd{C-_}, set up to run it is that it is worthy of a single-character
        !          2136: key, but the way to type @kbd{C-_} on some keyboards is not obvious.
        !          2137: @kbd{C-x u} is an alternative you can type in the same fashion on any
        !          2138: terminal.
        !          2139: 
        !          2140: @node Minibuffer, M-x, Undo, Top
        !          2141: @chapter The Minibuffer
        !          2142: @cindex minibuffer
        !          2143: 
        !          2144:   The @dfn{minibuffer} is the facility used by Emacs commands to read
        !          2145: arguments more complicated than a single number.  Minibuffer arguments can
        !          2146: be file names, buffer names, Lisp function names, Emacs command names, Lisp
        !          2147: expressions, and many other things, depending on the command reading the
        !          2148: argument.  The usual Emacs editing commands can be used in the minibuffer
        !          2149: to edit the argument.
        !          2150: 
        !          2151: @cindex prompt
        !          2152:   When the minibuffer is in use, it appears in the echo area, and the
        !          2153: terminal's cursor moves there.  The beginning of the minibuffer line
        !          2154: displays a @dfn{prompt} which says what kind of input you should supply and
        !          2155: how it will be used.  Often this prompt is derived from the name of the
        !          2156: command that the argument is for.  The prompt normally ends with a colon.
        !          2157: 
        !          2158: @cindex default argument
        !          2159:   Sometimes a @dfn{default argument} appears in parentheses after the
        !          2160: colon; it too is part of the prompt.  The default will be used as the
        !          2161: argument value if you enter an empty argument (e.g., just type @key{RET}).
        !          2162: For example, commands that read buffer names always show a default, which
        !          2163: is the name of the buffer that will be used if you type just @key{RET}.
        !          2164: 
        !          2165: @kindex C-g
        !          2166:   The simplest way to give a minibuffer argument is to type the text you
        !          2167: want, terminated by @key{RET} which exits the minibuffer.  You can get out
        !          2168: of the minibuffer, canceling the command that it was for, by typing
        !          2169: @kbd{C-g}.
        !          2170: 
        !          2171:   Since the minibuffer uses the screen space of the echo area, it can
        !          2172: conflict with other ways Emacs customarily uses the echo area.  Here is how
        !          2173: Emacs handles such conflicts:
        !          2174: 
        !          2175: @itemize @bullet
        !          2176: @item
        !          2177: If a command gets an error while you are in the minibuffer, this does
        !          2178: not cancel the minibuffer.  However, the echo area is needed for the
        !          2179: error message and therefore the minibuffer itself is hidden for a
        !          2180: while.  It comes back after a few seconds, or as soon as you type
        !          2181: anything.
        !          2182: 
        !          2183: @item
        !          2184: If in the minibuffer you use a command whose purpose is to print a
        !          2185: message in the echo area, such as @kbd{C-x =}, the message is printed
        !          2186: normally, and the minibuffer is hidden for a while.  It comes back
        !          2187: after a few seconds, or as soon as you type anything.
        !          2188: 
        !          2189: @item
        !          2190: Echoing of keystrokes does not take place while the minibuffer is in
        !          2191: use.
        !          2192: @end itemize
        !          2193: 
        !          2194: @menu
        !          2195: * File: Minibuffer File.  Entering file names with the minibuffer.
        !          2196: * Edit: Minibuffer Edit.  How to edit in the minibuffer.
        !          2197: * Completion::           An abbreviation facility for minibuffer input.
        !          2198: * Repetition::           Re-executing commands that used the minibuffer.
        !          2199: @end menu
        !          2200: 
        !          2201: @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
        !          2202: @section Minibuffers for File Names
        !          2203: 
        !          2204:   Sometimes the minibuffer starts out with text in it.  For example, when
        !          2205: you are supposed to give a file name, the minibuffer starts out containing
        !          2206: the @dfn{default directory}, which ends with a slash.  This is to inform
        !          2207: you which directory the file will be found in if you do not specify a
        !          2208: directory.  For example, the minibuffer might start out with
        !          2209: 
        !          2210: @example
        !          2211: Find File: /u2/emacs/src/
        !          2212: @end example
        !          2213: 
        !          2214: @noindent
        !          2215: where @samp{Find File:@: } is the prompt.  Typing @kbd{buffer.c} specifies
        !          2216: the file @file{/u2/emacs/src/buffer.c}.  To find files in nearby
        !          2217: directories, use @kbd{..}; thus, if you type @kbd{../lisp/simple.el}, the
        !          2218: file that you visit will be the one named @file{/u2/emacs/lisp/simple.el}.
        !          2219: Alternatively, you can kill with @kbd{M-@key{DEL}} the directory names you
        !          2220: don't want (@pxref{Words}).@refill
        !          2221: 
        !          2222:   You can also type an absolute file name, one starting with a slash or a
        !          2223: tilde, ignoring the default directory.  For example, to find the file
        !          2224: @file{/etc/termcap}, just type the name, giving
        !          2225: 
        !          2226: @example
        !          2227: Find File: /u2/emacs/src//etc/termcap
        !          2228: @end example
        !          2229: 
        !          2230: @noindent
        !          2231: Two slashes in a row are not normally meaningful in Unix file names, but
        !          2232: they are allowed in GNU Emacs.  They mean, ``ignore everything before the
        !          2233: second slash in the pair.''  Thus, @samp{/u2/emacs/src/} is ignored, and
        !          2234: you get the file @file{/etc/termcap}.
        !          2235: 
        !          2236: @vindex insert-default-directory
        !          2237:   If you set @code{insert-default-directory} to @code{nil}, the default directory
        !          2238: is not inserted in the minibuffer.  This way, the minibuffer starts out
        !          2239: empty.  But the name you type, if relative, is still interpreted with
        !          2240: respect to the same default directory.
        !          2241: 
        !          2242: @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
        !          2243: @section Editing in the Minibuffer
        !          2244: 
        !          2245:   The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
        !          2246: Emacs commands are available for editing the text of an argument you are
        !          2247: entering.
        !          2248: 
        !          2249:   Since @key{RET} in the minibuffer is defined to exit the minibuffer,
        !          2250: inserting a newline into the minibuffer must be done with @kbd{C-o} or with
        !          2251: @kbd{C-q @key{LFD}}.  (Recall that a newline is really the @key{LFD}
        !          2252: character.)
        !          2253: 
        !          2254:   The minibuffer has its own window which always has space on the screen
        !          2255: but acts as if it were not there when the minibuffer is not in use.  When
        !          2256: the minibuffer is in use, its window is just like the others; you can
        !          2257: switch to another window with @kbd{C-x o}, edit text in other windows and
        !          2258: perhaps even visit more files, before returning to the minibuffer to submit
        !          2259: the argument.  You can kill text in another window, return to the
        !          2260: minibuffer window, and then yank the text to use it in the argument.
        !          2261: @xref{Windows}.
        !          2262: 
        !          2263:   There are some restrictions on the use of the minibuffer window, however.
        !          2264: You cannot switch buffers in it---the minibuffer and its window are
        !          2265: permanently attached.  Also, you cannot split or kill the minibuffer
        !          2266: window.  But you can make it taller in the normal fashion with
        !          2267: @kbd{C-x ^} (@pxref{Change Window}).
        !          2268: 
        !          2269: @kindex C-M-v
        !          2270:   If while in the minibuffer you issue a command that displays help text
        !          2271: of any sort in another window, then that window is identified as the
        !          2272: one to scroll if you type @kbd{C-M-v} while in the minibuffer.  This
        !          2273: lasts until you exit the minibuffer.  This feature comes into play
        !          2274: if a completing minibuffer gives you a list of possible completions.
        !          2275: 
        !          2276: @cindex recursive minibuffer
        !          2277:   Recursive use of the minibuffer is supported by Emacs.  However, it is
        !          2278: easy to do this by accident (because of autorepeating keyboards, for
        !          2279: example) and get confused.  Therefore, most Emacs commands that use the
        !          2280: minibuffer refuse to operate if the minibuffer window is selected.  If the
        !          2281: minibuffer is active but you have switched to a different window, recursive
        !          2282: use of the minibuffer is allowed---if you know enough to try to do this,
        !          2283: you probably will not get confused.
        !          2284: 
        !          2285: @vindex enable-recursive-minibuffers
        !          2286:   If you set the variable @code{enable-recursive-minibuffers} to be
        !          2287: non-@code{nil}, recursive use of the minibuffer is always allowed.
        !          2288: 
        !          2289: @node Completion, Repetition, Minibuffer Edit, Minibuffer
        !          2290: @section Completion
        !          2291: @cindex completion
        !          2292: 
        !          2293:   When appropriate, the minibuffer provides a @dfn{completion} facility.
        !          2294: This means that you type enough of the argument to determine the rest,
        !          2295: based on Emacs's knowledge of which arguments make sense, and Emacs visibly
        !          2296: fills in the rest, or as much as can be determined from the part you have
        !          2297: typed.
        !          2298: 
        !          2299:   When completion is available, certain keys---@key{TAB}, @key{RET}, and @key{SPC}---are
        !          2300: redefined to complete an abbreviation present in the minibuffer into a
        !          2301: longer string that it stands for, by matching it against a set of
        !          2302: @dfn{completion alternatives} provided by the command reading the argument.
        !          2303: @kbd{?} is defined to display a list of possible completions of what you
        !          2304: have inserted.
        !          2305: 
        !          2306:   For example, when the minibuffer is being used by @kbd{Meta-x} to read
        !          2307: the name of a command, it is given a list of all available Emacs command
        !          2308: names to complete against.  The completion keys match the text in the
        !          2309: minibuffer against all the command names, find any additional characters of
        !          2310: the name that are implied by the ones already present in the minibuffer,
        !          2311: and add those characters to the ones you have given.
        !          2312: 
        !          2313:   Case is normally significant in completion, because it is significant in
        !          2314: most of the names that you can complete (buffer names, file names and
        !          2315: command names).  Thus, @samp{fo} will not complete to @samp{Foo}.  When you
        !          2316: are completing a name in which case does not matter, case may be ignored
        !          2317: for completion's sake if the program said to do so.
        !          2318: 
        !          2319: @subsection Completion Example
        !          2320: 
        !          2321: @kindex TAB
        !          2322: @findex minibuffer-complete
        !          2323:   A concrete example may help here.  If you type @kbd{Meta-x au @key{TAB}},
        !          2324: the @key{TAB} looks for alternatives (in this case, command names) that
        !          2325: start with @samp{au}.  There are only two: @code{auto-fill-mode} and
        !          2326: @code{auto-save-mode}.  These are the same as far as @code{auto-}, so the
        !          2327: @samp{au} in the minibuffer changes to @samp{auto-}.@refill
        !          2328: 
        !          2329:   If you type @key{TAB} again immediately, there are multiple possibilities
        !          2330: for the very next character---it could be @samp{s} or @samp{f}---so no more
        !          2331: characters are added; but a list of all possible completions is displayed
        !          2332: in another window.
        !          2333: 
        !          2334:   If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees
        !          2335: @samp{auto-f}.  The only command name starting this way is
        !          2336: @code{auto-fill-mode}, so completion inserts the rest of that.  You
        !          2337: now have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
        !          2338: @key{TAB} f @key{TAB}}.  Note that @key{TAB} has this effect because in the
        !          2339: minibuffer it is bound to the function @code{minibuffer-complete} when
        !          2340: completion is supposed to be done.@refill
        !          2341: 
        !          2342: @subsection Completion Commands
        !          2343: 
        !          2344:   Here is a list of all the completion commands, defined in the minibuffer
        !          2345: when completion is available.
        !          2346: 
        !          2347: @table @kbd
        !          2348: @item @key{TAB}
        !          2349: @c !!! added @* to prevent overfull hbox
        !          2350: Complete the text in the minibuffer as much as possible@*
        !          2351: (@code{minibuffer-complete}).
        !          2352: @item @key{SPC}
        !          2353: Complete the text in the minibuffer but don't add or fill out more
        !          2354: than one word (@code{minibuffer-complete-word}).
        !          2355: @item @key{RET}
        !          2356: Submit the text in the minibuffer as the argument, possibly completing
        !          2357: first as described below (@code{minibuffer-complete-and-exit}).
        !          2358: @item ?
        !          2359: Print a list of all possible completions of the text in the minibuffer
        !          2360: (@code{minibuffer-list-completions}).
        !          2361: @end table
        !          2362: 
        !          2363: @kindex SPC
        !          2364: @findex minibuffer-complete-word
        !          2365:   @key{SPC} completes much like @key{TAB}, but never goes beyond the
        !          2366: next hyphen or space.  If you have @samp{auto-f} in the minibuffer and type
        !          2367: @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, but it
        !          2368: stops completing after @samp{fill-}.  This gives @samp{auto-fill-}.
        !          2369: Another @key{SPC} at this point completes all the way to
        !          2370: @samp{auto-fill-mode}.  @key{SPC} in the minibuffer runs the function
        !          2371: @code{minibuffer-complete-word} when completion is available.@refill
        !          2372: 
        !          2373:   There are three different ways that @key{RET} can work in completing
        !          2374: minibuffers, depending on how the argument will be used.
        !          2375: 
        !          2376: @itemize @bullet
        !          2377: @item
        !          2378: @dfn{Strict} completion is used when it is meaningless to give any
        !          2379: argument except one of the known alternatives.  For example, when
        !          2380: @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
        !          2381: give anything but the name of an existing buffer.  In strict
        !          2382: completion, @key{RET} refuses to exit if the text in the minibuffer
        !          2383: does not complete to an exact match.
        !          2384: 
        !          2385: @item
        !          2386: @dfn{Cautious} completion is similar to strict completion, except that
        !          2387: @key{RET} exits only if the text was an exact match already, not
        !          2388: needing completion.  If the text is not an exact match, @key{RET} does
        !          2389: not exit, but it does complete the text.  If it completes to an exact
        !          2390: match, a second @key{RET} will exit.
        !          2391: 
        !          2392: Cautious completion is used for reading file names for files that must
        !          2393: already exist.
        !          2394: 
        !          2395: @item
        !          2396: @dfn{Permissive} completion is used when any string whatever is
        !          2397: meaningful, and the list of completion alternatives is just a guide.
        !          2398: For example, when @kbd{C-x C-f} reads the name of a file to visit, any
        !          2399: file name is allowed, in case you want to create a file.  In
        !          2400: permissive completion, @key{RET} takes the text in the minibuffer
        !          2401: exactly as given, without completing it.
        !          2402: @end itemize
        !          2403: 
        !          2404:   The completion commands display a list of all possible completions in a
        !          2405: window whenever there is more than one possibility for the very next
        !          2406: character.  Also, typing @kbd{?} explicitly requests such a list.  The
        !          2407: list of completions counts as help text, so @kbd{C-M-v} typed in the
        !          2408: minibuffer scrolls the list.
        !          2409: 
        !          2410: @vindex completion-ignored-extensions
        !          2411:   When completion is done on file names, certain file names are usually
        !          2412: ignored.  The variable @code{completion-ignored-extensions} contains a list
        !          2413: of strings; a file whose name ends in any of those strings is ignored as a
        !          2414: possible completion.  The standard value of this variable has several
        !          2415: elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and @code{"~"}.
        !          2416: The effect is that, for example, @samp{foo} can complete to @samp{foo.c}
        !          2417: even though @samp{foo.o} exists as well.  If the only possible completions
        !          2418: are files that end in ``ignored'' strings, then they are not ignored.@refill
        !          2419: 
        !          2420: @vindex completion-auto-help
        !          2421:   Normally, a completion command that finds the next character is undetermined
        !          2422: automatically displays a list of all possible completions.  If the variable
        !          2423: @code{completion-auto-help} is set to @code{nil}, this does not happen,
        !          2424: and you must type @kbd{?} to display the possible completions.
        !          2425: 
        !          2426: @node Repetition,, Completion, Minibuffer
        !          2427: @section Repeating Minibuffer Commands
        !          2428: @cindex command history
        !          2429: @cindex history of commands
        !          2430: 
        !          2431:   Every command that uses the minibuffer at least once is recorded on a
        !          2432: special history list, together with the values of the minibuffer arguments,
        !          2433: so that you can repeat the command easily.  In particular, every
        !          2434: use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to
        !          2435: read the command name.
        !          2436: 
        !          2437: @findex list-command-history
        !          2438: @c widecommands
        !          2439: @table @kbd
        !          2440: @c !!! following generates acceptable underfull hbox
        !          2441: @item C-x @key{ESC}
        !          2442: Re-execute a recent minibuffer command @code{repeat-complex-command}).
        !          2443: @item M-p
        !          2444: @c !!! added @* to prevent overfull hbox
        !          2445: Within @kbd{C-x @key{ESC}}, move to the previous recorded command@*
        !          2446: (@code{previous-complex-command}).
        !          2447: @item M-n
        !          2448: Within @kbd{C-x @key{ESC}}, move to the next (more recent) recorded
        !          2449: command (@code{next-complex-command}).
        !          2450: @item M-x list-command-history
        !          2451: Display the entire command history, showing all the commands
        !          2452: @kbd{C-x @key{ESC}} can repeat, most recent first.
        !          2453: @end table
        !          2454: 
        !          2455: @kindex C-x ESC
        !          2456: @findex repeat-complex-command
        !          2457:   @kbd{C-x @key{ESC}} is used to re-execute a recent minibuffer-using
        !          2458: command.  With no argument, it repeats the last such command.  A numeric
        !          2459: argument specifies which command to repeat; 1 means the last one, and
        !          2460: larger numbers specify earlier ones.
        !          2461: 
        !          2462:   @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp
        !          2463: expression and then entering a minibuffer initialized with the text for
        !          2464: that expression.  If you type just @key{RET}, the command is repeated as
        !          2465: before.  You can also change the command by editing the Lisp expression.
        !          2466: Whatever expression you finally submit is what will be executed.  The
        !          2467: repeated command is added to the front of the command history unless it is
        !          2468: identical to the most recently executed command already there.
        !          2469: 
        !          2470:   Even if you don't understand Lisp syntax, it will probably be obvious
        !          2471: which command is displayed for repetition.  If you do not change the text,
        !          2472: you can be sure it will repeat exactly as before.
        !          2473: 
        !          2474: @kindex M-n
        !          2475: @kindex M-p
        !          2476: @findex next-complex-command
        !          2477: @findex previous-complex-command
        !          2478:   Once inside the minibuffer for @kbd{C-x @key{ESC}}, if the command shown
        !          2479: to you is not the one you want to repeat, you can move around the list of
        !          2480: previous commands using @kbd{M-n} and @kbd{M-p}.  @kbd{M-p} replaces the
        !          2481: contents of the minibuffer with the next earlier recorded command, and
        !          2482: @kbd{M-n} replaces them with the next later command.  After finding the
        !          2483: desired previous command, you can edit its expression as usual and then
        !          2484: resubmit it by typing @key{RET} as usual.  Any editing you have done on the
        !          2485: command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
        !          2486: 
        !          2487:   @kbd{M-p} is more useful than @kbd{M-n}, since more often you will
        !          2488: initially request to repeat the most recent command and then decide to
        !          2489: repeat an older one instead.  These keys are specially defined within
        !          2490: @kbd{C-x @key{ESC}} to run the commands @code{previous-complex-command} and
        !          2491: @code{next-complex-command}.
        !          2492: 
        !          2493: @vindex command-history
        !          2494:   The list of previous minibuffer-using commands is stored as a Lisp list
        !          2495: in the variable @code{command-history}.  Each element is a Lisp expression
        !          2496: which describes one command and its arguments.  Lisp programs can reexecute
        !          2497: a command by feeding the corresponding @code{command-history} element to
        !          2498: @code{eval}.
        !          2499: 
        !          2500: @node M-x, Help, Minibuffer, Top
        !          2501: @chapter Running Commands by Name
        !          2502: 
        !          2503:   The Emacs commands that are used often or that must be quick to type are
        !          2504: bound to keys---short sequences of characters---for convenient use.  Other
        !          2505: Emacs commands that do not need to be brief are not bound to keys; to run
        !          2506: them, you must refer to them by name.
        !          2507: 
        !          2508:   A command name is, by convention, made up of one or more words, separated
        !          2509: by hyphens; for example, @code{auto-fill-mode} or @code{manual-entry}.  The
        !          2510: use of English words makes the command name easier to remember than a key
        !          2511: made up of obscure characters, even though it is more characters to type.
        !          2512: Any command can be run by name, even if it is also runnable by keys.
        !          2513: 
        !          2514: @kindex M-x
        !          2515: @cindex minibuffer
        !          2516:   The way to run a command by name is to start with @kbd{M-x}, type the
        !          2517: command name, and finish it with @key{RET}.  @kbd{M-x} uses the minibuffer
        !          2518: to read the command name.  @key{RET} exits the minibuffer and runs the
        !          2519: command.
        !          2520: 
        !          2521:   Emacs uses the minibuffer for reading input for many different purposes;
        !          2522: on this occasion, the string @samp{M-x} is displayed at the beginning of
        !          2523: the minibuffer as a @dfn{prompt} to remind you that your input should be
        !          2524: the name of a command to be run.  @xref{Minibuffer}, for full information
        !          2525: on the features of the minibuffer.
        !          2526: 
        !          2527:   You can use completion to enter the command name.  For example, the
        !          2528: command @code{forward-char} can be invoked by name by typing
        !          2529: 
        !          2530: @example
        !          2531: M-x forward-char @key{RET}
        !          2532: 
        !          2533: @exdent or
        !          2534: 
        !          2535: M-x fo @key{TAB} c @key{RET}
        !          2536: @end example
        !          2537: 
        !          2538: @noindent
        !          2539: Note that @code{forward-char} is the same command that you invoke with
        !          2540: the key @kbd{C-f}.  Any command (interactively callable function) defined
        !          2541: in Emacs can be called by its name using @kbd{M-x} whether or not any
        !          2542: keys are bound to it.
        !          2543: 
        !          2544:   If you type @kbd{C-g} while the command name is being read, you cancel
        !          2545: the @kbd{M-x} command and get out of the minibuffer, ending up at top level.
        !          2546: 
        !          2547:   To pass a numeric argument to the command you are invoking with
        !          2548: @kbd{M-x}, specify the numeric argument before the @kbd{M-x}.  @kbd{M-x}
        !          2549: passes the argument along to the function which it calls.  The argument
        !          2550: value appears in the prompt while the command name is being read.
        !          2551: 
        !          2552:   Normally, when describing a command that is run by name, we omit the
        !          2553: @key{RET} that is needed to terminate the name.  Thus we might speak of
        !          2554: @kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode @key{RET}}.
        !          2555: We mention the @key{RET} only when there is a need to emphasize its
        !          2556: presence, such as when describing a sequence of input that contains a
        !          2557: command name and arguments that follow it.
        !          2558: 
        !          2559: @findex execute-extended-command
        !          2560:   @kbd{M-x} is defined to run the command @code{execute-extended-command},
        !          2561: which is responsible for reading the name of another command and invoking
        !          2562: it.
        !          2563: 
        !          2564: @node Help, Mark, M-x, Top
        !          2565: @chapter Help
        !          2566: @kindex Help
        !          2567: @cindex help
        !          2568: @cindex self-documentation
        !          2569: 
        !          2570:   Emacs provides extensive help features which revolve around a single
        !          2571: character, @kbd{C-h}.  @kbd{C-h} is a prefix key that is used only for
        !          2572: documentation-printing commands.  The characters that you can type after
        !          2573: @kbd{C-h} are called @dfn{help options}.  One help option is @kbd{C-h};
        !          2574: that is how you ask for help about using @kbd{C-h}.
        !          2575: 
        !          2576:   @kbd{C-h C-h} prints a list of the possible help options, and then asks
        !          2577: you to go ahead and type the option.  It prompts with a string
        !          2578: 
        !          2579: @smallexample
        !          2580: A B C F I K L M N S T V W C-c C-d C-n C-w.  Type C-h again for more help:
        !          2581: @end smallexample
        !          2582: 
        !          2583: @noindent
        !          2584: and you should type one of those characters.
        !          2585: 
        !          2586:   Typing a third @kbd{C-h} displays a description of what the options mean;
        !          2587: it still waits for you to type an option.  To cancel, type @kbd{C-g}.
        !          2588: 
        !          2589:   Here is a summary of the defined help commands.
        !          2590: 
        !          2591: @table @kbd
        !          2592: @item C-h a @var{string} @key{RET}
        !          2593: @c !!! added @* to prevent overfull hbox
        !          2594: Display a list of commands whose names contain @var{string}@*
        !          2595: (@code{command-apropos}).
        !          2596: @item C-h b
        !          2597: Display a table of all key bindings in effect now; local bindings of
        !          2598: the current major mode first, followed by all global bindings
        !          2599: (@code{describe-bindings}).
        !          2600: @item C-h c @var{key}
        !          2601: Print the name of the command that @var{key} runs (@code{describe-key-briefly}).
        !          2602: @kbd{c} is for `character'.  For more extensive information on @var{key},
        !          2603: use @kbd{C-h k}.
        !          2604: @item C-h f @var{function} @key{RET}
        !          2605: Display documentation on the Lisp function named @var{function}
        !          2606: (@code{describe-function}).  Note that commands are Lisp functions, so
        !          2607: a command name may be used.
        !          2608: @item C-h i
        !          2609: Run Info, the program for browsing documentation files (@code{info}).
        !          2610: The complete Emacs manual is available on-line in Info.
        !          2611: @item C-h k @var{key}
        !          2612: Display name and documentation of the command @var{key} runs (@code{describe-key}).
        !          2613: @item C-h l
        !          2614: Display a description of the last 100 characters you typed
        !          2615: (@code{view-lossage}).
        !          2616: @item C-h m
        !          2617: Display documentation of the current major mode (@code{describe-mode}).
        !          2618: @item C-h n
        !          2619: Display documentation of Emacs changes, most recent first
        !          2620: (@code{view-emacs-news}).
        !          2621: @item C-h s
        !          2622: Display current contents of the syntax table, plus an explanation of
        !          2623: what they mean (@code{describe-syntax}).
        !          2624: @item C-h t
        !          2625: Display the Emacs tutorial (@code{help-with-tutorial}).
        !          2626: @item C-h v @var{var} @key{RET}
        !          2627: Display the documentation of the Lisp variable @var{var}
        !          2628: (@code{describe-variable}).
        !          2629: @item C-h w @var{command} @key{RET}
        !          2630: Print which keys run the command named @var{command} (@code{where-is}).
        !          2631: @end table
        !          2632: 
        !          2633: @section Documentation for a Key
        !          2634: 
        !          2635: @kindex C-h c
        !          2636: @findex describe-key-briefly
        !          2637:   The most basic @kbd{C-h} options are @kbd{C-h c}
        !          2638: (@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}).
        !          2639: @kbd{C-h c @var{key}} prints in the echo area the name of the command that
        !          2640: @var{key} is bound to.  For example, @kbd{C-h c C-f} prints
        !          2641: @samp{forward-char}.  Since command names are chosen to describe what the
        !          2642: command does, this is a good way to get a very brief description of what
        !          2643: @var{key} does.@refill
        !          2644: 
        !          2645: @kindex C-h k
        !          2646: @findex describe-key
        !          2647:   @kbd{C-h k @var{key}} is similar but gives more information.  It displays
        !          2648: the documentation string of the command @var{key} is bound to as well as
        !          2649: its name.  This is too big for the echo area, so a window is used for the
        !          2650: display.
        !          2651: 
        !          2652: @section Help by Command or Variable Name
        !          2653: 
        !          2654: @kindex C-h f
        !          2655: @findex describe-function
        !          2656:   @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function
        !          2657: using the minibuffer, then displays that function's documentation string
        !          2658: in a window.  Since commands are Lisp functions, you can use this to get
        !          2659: the documentation of a command that is known by name.  For example,
        !          2660: 
        !          2661: @example
        !          2662: C-h f auto-fill-mode @key{RET}
        !          2663: @end example
        !          2664: 
        !          2665: @noindent
        !          2666: displays the documentation of @code{auto-fill-mode}.  This is the only
        !          2667: way to see the documentation of a command that is not bound to any key
        !          2668: (one which you would normally call using @kbd{M-x}).
        !          2669: 
        !          2670:   @kbd{C-h f} is also useful for Lisp functions that you are planning to
        !          2671: use in a Lisp program.  For example, if you have just written the code
        !          2672: @code{(make-vector len)} and want to be sure that you are using
        !          2673: @code{make-vector} properly, type
        !          2674: @w{@kbd{C-h f make-vector @key{RET}}}.  Because @kbd{C-h f} allows 
        !          2675: all function names, not just command names, you may find that some of
        !          2676: your favorite abbreviations that work in @kbd{M-x} don't work in
        !          2677: @kbd{C-h f}.  An abbreviation may be unique among command names yet
        !          2678: fail to be unique when other function names are allowed.
        !          2679: 
        !          2680:   The function name for @kbd{C-h f} to describe has a default which is
        !          2681: used if you type @key{RET} leaving the minibuffer empty.  The default is
        !          2682: the function called by the innermost Lisp expression in the buffer around
        !          2683: point, @i{provided} that is a valid, defined Lisp function name.  For
        !          2684: example, if point is located following the text @samp{(make-vector (car
        !          2685: x)}, the innermost list containing point is the one that starts with
        !          2686: @samp{(make-vector}, so the default is to describe the function
        !          2687: @code{make-vector}.
        !          2688: 
        !          2689:   @kbd{C-h f} is often useful just to verify that you have the right
        !          2690: spelling for the function name.  If @kbd{C-h f} mentions a default in the
        !          2691: prompt, you have typed the name of a defined Lisp function.  If that tells
        !          2692: you what you want to know, just type @kbd{C-g} to cancel the @kbd{C-h f}
        !          2693: command and go on editing.
        !          2694: 
        !          2695: @kindex C-h w
        !          2696: @findex where-is
        !          2697:   @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to
        !          2698: @var{command}.  It prints a list of the keys in the echo area.
        !          2699: Alternatively, it says that the command is not on any keys, which implies
        !          2700: that you must use @kbd{M-x} to call it.@refill
        !          2701: 
        !          2702: @kindex C-h v
        !          2703: @findex describe-variable
        !          2704:   @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes
        !          2705: Lisp variables instead of Lisp functions.  Its default is the Lisp symbol
        !          2706: around or before point, but only if that is the name of a known Lisp
        !          2707: variable.  @xref{Variables}.@refill
        !          2708: 
        !          2709: @section Apropos
        !          2710: 
        !          2711: @kindex C-h a
        !          2712: @findex command-apropos
        !          2713: @cindex apropos
        !          2714:   A more sophisticated sort of question to ask is, ``What are the commands
        !          2715: for working with files?''  For this, type @kbd{C-h a file @key{RET}}, which
        !          2716: displays a list of all command names that contain @samp{file}, such as
        !          2717: @code{copy-file}, @code{find-file}, and so on.  With each command name
        !          2718: appears a brief description of how to use the command, and what keys you
        !          2719: can currently invoke it with.  For example, it would say that you can
        !          2720: invoke @code{find-file} by typing @kbd{C-x C-f}.  The @kbd{a} in @kbd{C-h
        !          2721: a} stands for `Apropos'; @kbd{C-h a} runs the Lisp function
        !          2722: @code{command-apropos}.@refill
        !          2723: 
        !          2724:   Because @kbd{C-h a} looks only for functions whose names contain the
        !          2725: string which you specify, you must use ingenuity in choosing the string.
        !          2726: If you are looking for commands for killing backwards and @kbd{C-h a
        !          2727: kill-backwards @key{RET}} doesn't reveal any, don't give up.  Try just
        !          2728: @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}.  Be persistent.
        !          2729: Pretend you are playing Adventure.  Also note that you can use a
        !          2730: regular expression as the argument (@pxref{Regexps}).
        !          2731: 
        !          2732:   Here is a set of arguments to give to @kbd{C-h a} that covers many
        !          2733: classes of Emacs commands, since there are strong conventions for naming
        !          2734: the standard Emacs commands.  By giving you a feel for the naming
        !          2735: conventions, this set should also serve to aid you in developing a
        !          2736: technique for picking @code{apropos} strings.
        !          2737: 
        !          2738: @quotation
        !          2739: char, line, word, sentence, paragraph, region, page, sexp, list, defun,
        !          2740: buffer, screen, window, file, dir, register, mode,
        !          2741: beginning, end, forward, backward, next, previous, up, down, search, goto,
        !          2742: kill, delete, mark, insert, yank, fill, indent, case,
        !          2743: change, set, what, list, find, view, describe.
        !          2744: @end quotation
        !          2745: 
        !          2746: @findex apropos
        !          2747:   To list all Lisp symbols that contain a match for a regexp, not just
        !          2748: the ones that are defined as commands, use the command @kbd{M-x apropos}
        !          2749: instead of @kbd{C-h a}.
        !          2750: 
        !          2751: @section Other Help Commands
        !          2752: 
        !          2753: @kindex C-h i
        !          2754: @findex info
        !          2755:   @kbd{C-h i} (@code{info}) runs the Info program, which is used for
        !          2756: browsing through structured documentation files.  The entire Emacs manual
        !          2757: is available within Info.  Eventually all the documentation of the GNU
        !          2758: system will be available.  Type @kbd{h} after entering Info to run
        !          2759: a tutorial on using Info.
        !          2760: 
        !          2761: @kindex C-h l
        !          2762: @findex view-lossage
        !          2763:   If something surprising happens, and you are not sure what commands you
        !          2764: typed, use @kbd{C-h l} (@code{view-lossage}).  @kbd{C-h l} prints the last
        !          2765: 100 command characters you typed in.  If you see commands that you don't
        !          2766: know, you can use @kbd{C-h c} to find out what they do.
        !          2767: 
        !          2768: @kindex C-h m
        !          2769: @findex describe-mode
        !          2770:   Emacs has several major modes, each of which redefines a few keys and
        !          2771: makes a few other changes in how editing works.  @kbd{C-h m} (@code{describe-mode})
        !          2772: prints documentation on the current major mode, which normally describes
        !          2773: all the commands that are changed in this mode.
        !          2774: 
        !          2775: @kindex C-h b
        !          2776: @findex describe-bindings
        !          2777:   @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s}
        !          2778: (@code{describe-syntax}) present other information about the current
        !          2779: Emacs mode.  @kbd{C-h b} displays a list of all the key bindings now
        !          2780: in effect; the local bindings of the current major mode first,
        !          2781: followed by the global bindings (@pxref{Key Bindings}).  @kbd{C-h s}
        !          2782: displays the contents of the syntax table, with explanations of each
        !          2783: character's syntax (@pxref{Syntax}).@refill
        !          2784: 
        !          2785: @kindex C-h n
        !          2786: @findex view-emacs-news
        !          2787: @kindex C-h t
        !          2788: @findex help-with-tutorial
        !          2789: @kindex C-h C-c
        !          2790: @findex describe-copying
        !          2791: @kindex C-h C-d
        !          2792: @findex describe-distribution
        !          2793: @kindex C-h C-w
        !          2794: @findex describe-no-warranty
        !          2795:   The other @kbd{C-h} options display various files of useful
        !          2796: information.  @w{@kbd{C-h C-w}} displays the full details on the complete
        !          2797: absence of warranty for GNU Emacs.  @kbd{C-h n} (@code{view-emacs-news})
        !          2798: displays the file @file{emacs/etc/NEWS}, which contains documentation on
        !          2799: Emacs changes arranged chronologically.  @kbd{C-h t}
        !          2800: (@code{help-with-tutorial}) displays the learn-by-doing Emacs tutorial.
        !          2801: @kbd{C-h C-c} (@code{describe-copying}) displays the file
        !          2802: @file{emacs/etc/COPYING}, which tells you the conditions you must obey
        !          2803: in distributing copies of Emacs.  @kbd{C-h C-d}
        !          2804: (@code{describe-distribution}) displays another file named
        !          2805: @file{emacs/etc/DISTRIB}, which tells you how you can order a copy of
        !          2806: the latest version of Emacs.
        !          2807: 
        !          2808: @node Mark, Killing, Help, Top
        !          2809: @chapter The Mark and the Region
        !          2810: @cindex mark
        !          2811: @cindex region
        !          2812: 
        !          2813:   There are many Emacs commands which operate on an arbitrary contiguous
        !          2814: part of the current buffer.  To specify the text for such a command to
        !          2815: operate on, you set the @dfn{mark} at one end of it, and move point to the
        !          2816: other end.  The text between point and the mark is called the @dfn{region}.
        !          2817: You can move point or the mark to adjust the boundaries of the region.  It
        !          2818: doesn't matter which one is set first chronologically, or which one comes
        !          2819: earlier in the text.
        !          2820: 
        !          2821:   Once the mark has been set, it remains until it is set again at another
        !          2822: place.  The mark remains fixed with respect to the preceding character if
        !          2823: text is inserted or deleted in the buffer.  Each Emacs buffer has its own
        !          2824: mark, so that when you return to a buffer that had been selected
        !          2825: previously, it has the same mark it had before.
        !          2826: 
        !          2827:   Many commands that insert text, such as @kbd{C-y} (@code{yank}) and
        !          2828: @kbd{M-x insert-buffer}, position the mark at one end of the inserted
        !          2829: text---the opposite end from where point is positioned, so that the region
        !          2830: contains the text just inserted.
        !          2831: 
        !          2832:   Aside from delimiting the region, the mark is also useful for remembering
        !          2833: a spot that you may want to go back to.  To make this feature more useful,
        !          2834: Emacs remembers 16 previous locations of the mark, in the @code{mark ring}.
        !          2835: 
        !          2836: @menu
        !          2837: * Setting Mark::       Commands to set the mark.
        !          2838: * Using Region::       Summary of ways to operate on contents of the region.
        !          2839: * Marking Objects::    Commands to put region around textual units.
        !          2840: * Mark Ring::   Previous mark positions saved so you can go back there.
        !          2841: @end menu
        !          2842: 
        !          2843: @node Setting Mark, Using Region, Mark, Mark
        !          2844: @section Setting the Mark
        !          2845: 
        !          2846:   Here are some commands for setting the mark:
        !          2847: 
        !          2848: @c WideCommands
        !          2849: @table @kbd
        !          2850: @item C-@key{SPC}
        !          2851: Set the mark where point is (@code{set-mark-command}).
        !          2852: @item C-@@
        !          2853: The same.
        !          2854: @item C-x C-x
        !          2855: Interchange mark and point (@code{exchange-point-and-mark}).
        !          2856: @end table
        !          2857: 
        !          2858:   For example, if you wish to convert part of the buffer to all upper-case,
        !          2859: you can use the @kbd{C-x C-u} (@code{upcase-region}) command, which operates
        !          2860: on the text in the region.  You can first go to the beginning of the text
        !          2861: to be capitalized, type @kbd{C-@key{SPC}} to put the mark there, move to
        !          2862: the end, and then type @kbd{C-x C-u}.  Or, you can set the mark at the end
        !          2863: of the text, move to the beginning, and then type @kbd{C-x C-u}.  Most
        !          2864: commands that operate on the text in the region have the word @code{region}
        !          2865: in their names.
        !          2866: 
        !          2867: @kindex C-SPC
        !          2868: @findex set-mark-command
        !          2869:   The most common way to set the mark is with the @kbd{C-@key{SPC}} command
        !          2870: (@code{set-mark-command}).  This sets the mark where point is.  Then you
        !          2871: can move point away, leaving the mark behind.  It is actually incorrect to
        !          2872: speak of the character @kbd{C-@key{SPC}}; there is no such character.  When
        !          2873: you type @key{SPC} while holding down @key{CTRL}, what you get on most
        !          2874: terminals is the character @kbd{C-@@}.  This is the key actually bound to
        !          2875: @code{set-mark-command}.  But unless you are unlucky enough to have a
        !          2876: terminal where typing @kbd{C-@key{SPC}} does not produce @kbd{C-@@}, you
        !          2877: might as well think of this character as @kbd{C-@key{SPC}}.
        !          2878: 
        !          2879: @kindex C-x C-x
        !          2880: @findex exchange-point-and-mark
        !          2881:   Since terminals have only one cursor, there is no way for Emacs to show
        !          2882: you where the mark is located.  You have to remember.  The usual solution
        !          2883: to this problem is to set the mark and then use it soon, before you forget
        !          2884: where it is.  But you can see where the mark is with the command @w{@kbd{C-x
        !          2885: C-x}} (@code{exchange-point-and-mark}) which puts the mark where point was and
        !          2886: point where the mark was.  The extent of the region is unchanged, but the
        !          2887: cursor and point are now at the previous location of the mark.
        !          2888: 
        !          2889:   @kbd{C-x C-x} is also useful when you are satisfied with the location of
        !          2890: point but want to move the mark; do @kbd{C-x C-x} to put point there and
        !          2891: then you can move it.  A second use of @kbd{C-x C-x}, if necessary, puts
        !          2892: the mark at the new location with point back at its original location.
        !          2893: 
        !          2894: @node Using Region, Marking Objects, Setting Mark, Mark
        !          2895: @section Operating on the Region
        !          2896: 
        !          2897:   Once you have created an active region, you can do many things to
        !          2898: the text in it:
        !          2899: @itemize @bullet
        !          2900: @item
        !          2901: Kill it with @kbd{C-w} (@pxref{Killing}).
        !          2902: @item
        !          2903: Save it in a register with @kbd{C-x x} (@pxref{Registers}).
        !          2904: @item
        !          2905: Save it in a buffer or a file (@pxref{Accumulating Text}).
        !          2906: @item
        !          2907: @c !!! added @* to prevent overfull hbox
        !          2908: Convert case with @kbd{C-x C-l} or @kbd{C-x C-u}@*
        !          2909: (@pxref{Case}).
        !          2910: @item
        !          2911: Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}).
        !          2912: @item
        !          2913: Fill it as text with @kbd{M-g} (@pxref{Filling}).
        !          2914: @item
        !          2915: Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}).
        !          2916: @item
        !          2917: @c !!! added @* to prevent overfull hbox
        !          2918: Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\}@*
        !          2919: (@pxref{Indentation}).
        !          2920: @end itemize
        !          2921: 
        !          2922: @node Marking Objects, Mark Ring, Using Region, Mark
        !          2923: @section Commands to Mark Textual Objects
        !          2924: 
        !          2925:   There are commands for placing point and the mark around a textual
        !          2926: object such as a word, list, paragraph or page.
        !          2927: 
        !          2928: @table @kbd
        !          2929: @item M-@@
        !          2930: Set mark after end of next word (@code{mark-word}).  This command and
        !          2931: the following one do not move point.
        !          2932: @item C-M-@@
        !          2933: Set mark after end of next Lisp expression (@code{mark-sexp}).
        !          2934: @item M-h
        !          2935: Put region around current paragraph (@code{mark-paragraph}).
        !          2936: @item C-M-h
        !          2937: Put region around current Lisp defun (@code{mark-defun}).
        !          2938: @item C-x h
        !          2939: Put region around entire buffer (@code{mark-whole-buffer}).
        !          2940: @item C-x C-p
        !          2941: Put region around current page (@code{mark-page}).
        !          2942: @end table
        !          2943: 
        !          2944: @kindex M-@@
        !          2945: @kindex C-M-@@
        !          2946: @findex mark-word
        !          2947: @findex mark-sexp
        !          2948: @kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word,
        !          2949: while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp
        !          2950: expression.  These characters allow you to save a little typing or
        !          2951: redisplay, sometimes.
        !          2952: 
        !          2953: @kindex M-h
        !          2954: @kindex C-M-h
        !          2955: @kindex C-x C-p
        !          2956: @kindex C-x h
        !          2957: @findex mark-paragraph
        !          2958: @findex mark-defun
        !          2959: @findex mark-page
        !          2960: @findex mark-whole-buffer
        !          2961:    Other commands set both point and mark, to delimit an object in the
        !          2962: buffer.  @kbd{M-h} (@code{mark-paragraph}) moves point to the beginning of
        !          2963: the paragraph that surrounds or follows point, and puts the mark at the end
        !          2964: of that paragraph (@pxref{Paragraphs}).  @kbd{M-h} does all that's
        !          2965: necessary if you wish to indent, case-convert, or kill a whole paragraph.
        !          2966: @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the mark
        !          2967: after the current or following defun (@pxref{Defuns}).  @kbd{C-x C-p}
        !          2968: (@code{mark-page}) puts point before the current page (or the next or
        !          2969: previous, according to the argument), and mark at the end (@pxref{Pages}).
        !          2970: The mark goes after the terminating page delimiter (to include it), while
        !          2971: point goes after the preceding page delimiter (to exclude it).  Finally,
        !          2972: @w{@kbd{C-x h}} (@code{mark-whole-buffer}) sets up the entire buffer as the
        !          2973: region, by putting point at the beginning and the mark at the end.
        !          2974: 
        !          2975: @node Mark Ring,, Marking Objects, Mark
        !          2976: @section The Mark Ring
        !          2977: 
        !          2978: @kindex C-u C-SPC
        !          2979: @cindex mark ring
        !          2980: @kindex C-u C-@@
        !          2981:   Aside from delimiting the region, the mark is also useful for remembering
        !          2982: a spot that you may want to go back to.  To make this feature more useful,
        !          2983: Emacs remembers 16 previous locations of the mark, in the @dfn{mark ring}.
        !          2984: Most commands that set the mark push the old mark onto this ring.  To
        !          2985: return to a marked location, use @kbd{C-u C-@key{SPC}} (or @kbd{C-u C-@@}); this is
        !          2986: the command @code{set-mark-command} given a numeric argument.  It moves
        !          2987: point to where the mark was, and restores the mark from the ring of former
        !          2988: marks.  So repeated use of this command moves point to all of the old marks
        !          2989: on the ring, one by one.  The marks you see go to the end of the ring,
        !          2990: so no marks are lost.
        !          2991: 
        !          2992:   Each buffer has its own mark ring.  All editing commands use the current
        !          2993: buffer's mark ring.  In particular, @kbd{C-u C-@key{SPC}} always stays in
        !          2994: the same buffer.
        !          2995: 
        !          2996:   Many commands that can move long distances, such as @kbd{M-<}
        !          2997: (@code{beginning-of-buffer}), start by setting the mark and saving the old
        !          2998: mark on the mark ring.  This is to make it easier for you to move back
        !          2999: later.  Searches do this except when they do not actually move point.  You
        !          3000: can tell when a command sets the mark because @samp{Mark Set} is printed in
        !          3001: the echo area.
        !          3002: 
        !          3003:   Another way of remembering positions so you can go back to them is with
        !          3004: registers (@pxref{RegPos}).
        !          3005: 
        !          3006: @vindex mark-ring-max
        !          3007:   The variable @code{mark-ring-max} is the maximum number of entries to
        !          3008: keep in the mark ring.  If that many entries exist and another one is
        !          3009: pushed, the last one in the list is discarded.  Repeating @kbd{C-u
        !          3010: C-@key{SPC}} circulates through the limited number of entries that are
        !          3011: currently in the ring.
        !          3012: 
        !          3013: @vindex mark-ring
        !          3014:   The variable @code{mark-ring} holds the mark ring itself, as a list of
        !          3015: marker objects in the order most recent first.  This variable is local
        !          3016: in every buffer.
        !          3017: 
        !          3018: @iftex
        !          3019: @chapter Killing and Moving Text
        !          3020: 
        !          3021:   @dfn{Killing} means erasing text and copying it into the @dfn{kill ring},
        !          3022: from which it can be retrieved by @dfn{yanking} it.  Some other systems
        !          3023: that have recently become popular use the terms ``cutting'' and ``pasting''
        !          3024: for these operations.
        !          3025: 
        !          3026:   The commonest way of moving or copying text with Emacs is to kill it and
        !          3027: later yank it in one or more places.  This is very safe because all the
        !          3028: text killed recently is remembered, and it is versatile, because the many
        !          3029: commands for killing syntactic units can also be used for moving those
        !          3030: units.  There are also other ways of copying text for special purposes.
        !          3031: 
        !          3032:   Emacs has only one kill ring, so you can kill text in one buffer and yank
        !          3033: it in another buffer.
        !          3034: 
        !          3035: @end iftex
        !          3036: 
        !          3037: @node Killing, Yanking, Mark, Top
        !          3038: @section Deletion and Killing
        !          3039: @findex delete-char
        !          3040: @c ??? Should be backward-delete-char
        !          3041: @findex delete-backward-char
        !          3042: 
        !          3043: @cindex killing
        !          3044: @cindex cutting
        !          3045: @cindex clipping text
        !          3046: @cindex deletion
        !          3047: @kindex C-d
        !          3048: @kindex DEL
        !          3049:   Most commands which erase text from the buffer save it so that you can
        !          3050: get it back if you change your mind, or move or copy it to other parts of
        !          3051: the buffer.  These commands are known as @dfn{kill} commands.  The rest of
        !          3052: the commands that erase text do not save it; they are known as @dfn{delete}
        !          3053: commands.  (This distinction is made only for erasure of text in the
        !          3054: buffer.)
        !          3055: 
        !          3056: @c !!! following generates acceptable underfull hbox
        !          3057:   The delete commands include @kbd{C-d} (@code{delete-char}) and
        !          3058: @key{DEL} (@code{delete-backward-char}), which delete only one character at
        !          3059: a time, and those commands that delete only spaces or newlines.  Commands
        !          3060: that can destroy significant amounts of nontrivial data generally kill.
        !          3061: The commands' names and individual descriptions use the words @samp{kill}
        !          3062: and @samp{delete} to say which they do.  If you do a kill or delete command
        !          3063: by mistake, you can use the @w{@kbd{C-x u}} (@code{undo}) command to undo it
        !          3064: (@pxref{Undo}).
        !          3065: 
        !          3066: @subsection Deletion
        !          3067: 
        !          3068: @table @kbd
        !          3069: @item C-d
        !          3070: Delete next character (@code{delete-char}).
        !          3071: @item @key{DEL}
        !          3072: Delete previous character (@code{delete-backward-char}).
        !          3073: @item M-\
        !          3074: Delete spaces and tabs around point (@code{delete-horizontal-space}).
        !          3075: @item M-@key{SPC}
        !          3076: Delete spaces and tabs around point, leaving one space
        !          3077: (@code{just-one-space}).
        !          3078: @item C-x C-o
        !          3079: Delete blank lines around the current line (@code{delete-blank-lines}).
        !          3080: @item M-^
        !          3081: Join two lines by deleting the intervening newline, and any indentation
        !          3082: following it (@code{delete-indentation}).
        !          3083: @end table
        !          3084: 
        !          3085:   The most basic delete commands are @kbd{C-d} (@code{delete-char}) and
        !          3086: @key{DEL} (@code{delete-backward-char}).  @kbd{C-d} deletes the character
        !          3087: after point, the one the cursor is ``on top of''.  Point doesn't move.
        !          3088: @key{DEL} deletes the character before the cursor, and moves point back.
        !          3089: Newlines can be deleted like any other characters in the buffer; deleting a
        !          3090: newline joins two lines.  Actually, @kbd{C-d} and @key{DEL} aren't always
        !          3091: delete commands; if given an argument, they kill instead, since they can
        !          3092: erase more than one character this way.
        !          3093: 
        !          3094: @kindex M-\
        !          3095: @findex delete-horizontal-space
        !          3096: @kindex M-SPC
        !          3097: @findex just-one-space
        !          3098: @kindex C-x C-o
        !          3099: @findex delete-blank-lines
        !          3100: @kindex M-^
        !          3101: @findex delete-indentation
        !          3102:   The other delete commands are those which delete only formatting
        !          3103: characters: spaces, tabs and newlines.  @kbd{M-\} (@code{delete-horizontal-space})
        !          3104: deletes all the spaces and tab characters before and after point.
        !          3105: @kbd{M-@key{SPC}} (@code{just-one-space}) does likewise but leaves a single
        !          3106: space after point, regardless of the number of spaces that existed
        !          3107: previously (even zero).
        !          3108: 
        !          3109:   @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after
        !          3110: the current line, and if the current line is blank deletes all blank lines
        !          3111: preceding the current line as well (leaving one blank line, the current
        !          3112: line).  @kbd{M-^} (@code{delete-indentation}) joins the current line and
        !          3113: the previous line, or the current line and the next line if given an
        !          3114: argument, by deleting a newline and all surrounding spaces, possibly
        !          3115: leaving a single space.  @xref{Indentation,M-^}.
        !          3116: 
        !          3117: @subsection Killing by Lines
        !          3118: 
        !          3119: @table @kbd
        !          3120: @item C-k
        !          3121: Kill rest of line or one or more lines (@code{kill-line}).
        !          3122: @end table
        !          3123: 
        !          3124: @kindex C-k
        !          3125: @findex kill-line
        !          3126:   The simplest kill command is @kbd{C-k}.  If given at the beginning of a
        !          3127: line, it kills all the text on the line, leaving it blank.  If given on a
        !          3128: blank line, the blank line disappears.  As a consequence, if you go to the
        !          3129: front of a non-blank line and type @kbd{C-k} twice, the line disappears
        !          3130: completely.
        !          3131: 
        !          3132:   More generally, @kbd{C-k} kills from point up to the end of the line,
        !          3133: unless it is at the end of a line.  In that case it kills the newline
        !          3134: following the line, thus merging the next line into the current one.
        !          3135: Invisible spaces and tabs at the end of the line are ignored when deciding
        !          3136: which case applies, so if point appears to be at the end of the line, you
        !          3137: can be sure the newline will be killed.
        !          3138: 
        !          3139:   If @kbd{C-k} is given a positive argument, it kills that many lines and
        !          3140: the newlines that follow them (however, text on the current line before
        !          3141: point is spared).  With a negative argument, it kills back to a number of
        !          3142: line beginnings.  An argument of @minus{}2 means kill back to the second line
        !          3143: beginning.  If point is at the beginning of a line, that line beginning
        !          3144: doesn't count, so @w{@kbd{C-u - 2 C-k}} with point at the front of a line kills
        !          3145: the two previous lines.
        !          3146: 
        !          3147:   @kbd{C-k} with an argument of zero kills all the text before point on the
        !          3148: current line.
        !          3149: 
        !          3150: @subsection Other Kill Commands
        !          3151: @findex kill-line
        !          3152: @findex kill-region
        !          3153: @findex kill-word
        !          3154: @findex backward-kill-word
        !          3155: @findex kill-sexp
        !          3156: @findex kill-sentence
        !          3157: @findex backward-kill-sentence
        !          3158: @kindex M-d
        !          3159: @kindex M-DEL
        !          3160: @kindex C-M-k
        !          3161: @kindex C-x DEL
        !          3162: @kindex M-k
        !          3163: @kindex C-k
        !          3164: @kindex C-w
        !          3165: 
        !          3166: @c DoubleWideCommands
        !          3167: @table @kbd
        !          3168: @item C-w
        !          3169: Kill region (from point to the mark) (@code{kill-region}).
        !          3170: @xref{Words}.
        !          3171: @item M-d
        !          3172: Kill word (@code{kill-word}).
        !          3173: @item M-@key{DEL}
        !          3174: Kill word backwards (@code{backward-kill-word}).
        !          3175: @item C-x @key{DEL}
        !          3176: Kill back to beginning of sentence (@code{backward-kill-sentence}).
        !          3177: @xref{Sentences}.
        !          3178: @item M-k
        !          3179: Kill to end of sentence (@code{kill-sentence}).
        !          3180: @item C-M-k
        !          3181: Kill sexp (@code{kill-sexp}).  @xref{Lists}.
        !          3182: @item M-z @var{char}
        !          3183: Kill up to next occurrence of @var{char} (@code{zap-to-char}).
        !          3184: @end table
        !          3185: 
        !          3186:   A kill command which is very general is @kbd{C-w} (@code{kill-region}),
        !          3187: which kills everything between point and the mark.  With this command, you
        !          3188: can kill any contiguous sequence of characters, if you first set the mark
        !          3189: at one end of them and go to the other end.
        !          3190: 
        !          3191: @kindex M-z
        !          3192: @findex zap-to-char
        !          3193:   A convenient way of killing is combined with searching: @kbd{M-z}
        !          3194: (@code{zap-to-char}) reads a character and kills from point up to (but not
        !          3195: including) the next occurrence of that character in the buffer.  If there
        !          3196: is no next occurrence, killing goes to the end of the buffer.  A numeric
        !          3197: argument acts as a repeat count.  A negative argument means to search
        !          3198: backward and kill text before point.
        !          3199: 
        !          3200:   Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and
        !          3201: @kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and
        !          3202: sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k}
        !          3203: (@pxref{Sentences}).@refill
        !          3204: 
        !          3205: @node Yanking, Accumulating Text, Killing, Top
        !          3206: @section Yanking
        !          3207: @cindex moving text
        !          3208: @cindex copying text
        !          3209: @cindex kill ring
        !          3210: @cindex yanking
        !          3211: @cindex pasting
        !          3212: 
        !          3213:   @dfn{Yanking} is getting back text which was killed.  This is what some
        !          3214: systems call ``pasting''.  The usual way to move or copy text is to kill it
        !          3215: and then yank it one or more times.
        !          3216: 
        !          3217: @table @kbd
        !          3218: @item C-y
        !          3219: Yank last killed text (@code{yank}).
        !          3220: @item M-y
        !          3221: Replace re-inserted killed text with the previously killed text
        !          3222: (@code{yank-pop}).
        !          3223: @item M-w
        !          3224: Save region as last killed text without actually killing it
        !          3225: (@code{copy-region-as-kill}).
        !          3226: @item C-M-w
        !          3227: Append next kill to last batch of killed text (@code{append-next-kill}).
        !          3228: @end table
        !          3229: 
        !          3230: @menu
        !          3231: * Kill Ring::       Where killed text is stored.  Basic yanking.
        !          3232: * Appending Kills:: Several kills in a row all yank together.
        !          3233: * Earlier Kills::   Yanking something killed some time ago.
        !          3234: @end menu
        !          3235: 
        !          3236: @node Kill Ring, Appending Kills, Yanking, Yanking
        !          3237: @subsection The Kill Ring
        !          3238: 
        !          3239: @kindex C-y
        !          3240: @findex Yank
        !          3241:   All killed text is recorded in the @dfn{kill ring}, a list of blocks of
        !          3242: text that have been killed.  There is only one kill ring, used in all
        !          3243: buffers, so you can kill text in one buffer and yank it in another buffer.
        !          3244: This is the usual way to move text from one file to another.
        !          3245: (@xref{Accumulating Text}, for some other ways.)
        !          3246: 
        !          3247:   The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent
        !          3248: kill.  It leaves the cursor at the end of the text.  It sets the mark at
        !          3249: the beginning of the text.  @xref{Mark}.
        !          3250: 
        !          3251:   @kbd{C-u C-y} leaves the cursor in front of the text, and sets the mark
        !          3252: after it.  This is only if the argument is specified with just a @kbd{C-u},
        !          3253: precisely.  Any other sort of argument, including @kbd{C-u} and digits, has
        !          3254: an effect described below (under ``Yanking Earlier Kills'').
        !          3255: 
        !          3256: @kindex M-w
        !          3257: @findex copy-region-as-kill
        !          3258:   If you wish to copy a block of text, you might want to use @kbd{M-w}
        !          3259: (@code{copy-region-as-kill}), which copies the region into the kill ring
        !          3260: without removing it from the buffer.  This is approximately equivalent to
        !          3261: @kbd{C-w} followed by @kbd{C-y}, except that @kbd{M-w} does not mark the
        !          3262: buffer as ``modified'' and does not temporarily change the screen.
        !          3263: 
        !          3264: @node Appending Kills, Earlier Kills, Kill Ring, Yanking
        !          3265: @subsection Appending Kills
        !          3266: 
        !          3267: @cindex television
        !          3268:   Normally, each kill command pushes a new block onto the kill ring.
        !          3269: However, two or more kill commands in a row combine their text into a
        !          3270: single entry, so that a single @kbd{C-y} gets it all back as it was before
        !          3271: it was killed.  This means that you don't have to kill all the text in one
        !          3272: command; you can keep killing line after line, or word after word, until
        !          3273: you have killed it all, and you can still get it all back at once.  (Thus
        !          3274: we join television in leading people to kill thoughtlessly.)
        !          3275: 
        !          3276:   Commands that kill forward from point add onto the end of the previous
        !          3277: killed text.  Commands that kill backward from point add onto the
        !          3278: beginning.  This way, any sequence of mixed forward and backward kill
        !          3279: commands puts all the killed text into one entry without rearrangement.
        !          3280: Numeric arguments do not break the sequence of appending kills.  For
        !          3281: example, suppose the buffer contains
        !          3282: 
        !          3283: @example
        !          3284: This is the first
        !          3285: line of sample text
        !          3286: and here is the third.
        !          3287: @end example
        !          3288: 
        !          3289: @noindent
        !          3290: with point at the beginning of the second line.  If you type @kbd{C-k C-u 2
        !          3291: M-@key{DEL} C-k}, the first @kbd{C-k} kills the text @samp{line of sample
        !          3292: text}, @kbd{C-u 2 M-@key{DEL}} kills @samp{the first} with the newline that
        !          3293: followed it, and the second @kbd{C-k} kills the newline after the second
        !          3294: line.  The result is that the buffer contains @samp{This is and here is the
        !          3295: third.} and a single kill entry contains @samp{the first@key{RET}line of
        !          3296: sample text@key{RET}}---all the killed text, in its original order.
        !          3297: 
        !          3298: @kindex C-M-w
        !          3299: @findex append-next-kill
        !          3300:   If a kill command is separated from the last kill command by other
        !          3301: commands (not just numeric arguments), it starts a new entry on the kill
        !          3302: ring.  But you can force it to append by first typing the command
        !          3303: @kbd{C-M-w} (@code{append-next-kill}) in front of it.  The @kbd{C-M-w}
        !          3304: tells the following command, if it is a kill command, to append the text it
        !          3305: kills to the last killed text, instead of starting a new entry.  With
        !          3306: @kbd{C-M-w}, you can kill several separated pieces of text and accumulate
        !          3307: them to be yanked back in one place.@refill
        !          3308: 
        !          3309: @node Earlier Kills,, Appending Kills, Yanking
        !          3310: @subsection Yanking Earlier Kills
        !          3311: 
        !          3312: @kindex M-y
        !          3313: @findex yank-pop
        !          3314:   To recover killed text that is no longer the most recent kill, you need
        !          3315: the @kbd{Meta-y} (@code{yank-pop}) command.  @kbd{M-y} can be used only
        !          3316: after a @kbd{C-y} or another @kbd{M-y}.  It takes the text previously
        !          3317: yanked and replaces it with the text from an earlier kill.  So, to recover
        !          3318: the text of the next-to-the-last kill, you first use @kbd{C-y} to recover
        !          3319: the last kill, and then use @kbd{M-y} to replace it with the previous
        !          3320: kill.@refill
        !          3321: 
        !          3322:   You can think in terms of a ``last yank'' pointer which points at an item
        !          3323: in the kill ring.  Each time you kill, the ``last yank'' pointer moves to
        !          3324: the newly made item at the front of the ring.  @kbd{C-y} yanks the item
        !          3325: which the ``last yank'' pointer points to.  @kbd{M-y} moves the ``last
        !          3326: yank'' pointer to a different item, and the text in the buffer changes to
        !          3327: match.  Enough @kbd{M-y} commands can move the pointer to any item in the
        !          3328: ring, so you can get any item into the buffer.  Eventually the pointer
        !          3329: reaches the end of the ring; the next @kbd{M-y} moves it to the first item
        !          3330: again.
        !          3331: 
        !          3332:   Yanking moves the ``last yank'' pointer around the ring, but it does not
        !          3333: change the order of the entries in the ring, which always runs from the
        !          3334: most recent kill at the front to the oldest one still remembered.
        !          3335: 
        !          3336:   @kbd{M-y} can take a numeric argument, which tells it how many items to
        !          3337: advance the ``last yank'' pointer by.  A negative argument moves the
        !          3338: pointer toward the front of the ring; from the front of the ring, it moves
        !          3339: to the last entry and starts moving forward from there.
        !          3340: 
        !          3341:   Once the text you are looking for is brought into the buffer, you can
        !          3342: stop doing @kbd{M-y} commands and it will stay there.  It's just a copy of
        !          3343: the kill ring item, so editing it in the buffer does not change what's in
        !          3344: the ring.  As long as no new killing is done, the ``last yank'' pointer
        !          3345: remains at the same place in the kill ring, so repeating @kbd{C-y} will
        !          3346: yank another copy of the same old kill.
        !          3347: 
        !          3348:   If you know how many @kbd{M-y} commands it would take to find the
        !          3349: text you want, you can yank that text in one step using @kbd{C-y} with
        !          3350: a numeric argument.  @kbd{C-y} with an argument greater than one
        !          3351: restores the text the specified number of entries back in the kill
        !          3352: ring.  Thus, @kbd{C-u 2 C-y} gets the next to the last block of killed
        !          3353: text.  It is equivalent to @kbd{C-y M-y}.  @kbd{C-y} with a numeric
        !          3354: argument starts counting from the ``last yank'' pointer, and sets the
        !          3355: ``last yank'' pointer to the entry that it yanks.
        !          3356: 
        !          3357: @vindex kill-ring-max
        !          3358:   The length of the kill ring is controlled by the variable
        !          3359: @code{kill-ring-max}; no more than that many blocks of killed text are
        !          3360: saved.
        !          3361: 
        !          3362: @node Accumulating Text, Rectangles, Yanking, Top
        !          3363: @section Accumulating Text
        !          3364: @kindex C-x a
        !          3365: @findex append-to-buffer
        !          3366: @findex prepend-to-buffer
        !          3367: @findex copy-to-buffer
        !          3368: @findex append-to-file
        !          3369: 
        !          3370:   Usually we copy or move text by killing it and yanking it, but there are
        !          3371: other ways that are useful for copying one block of text in many places, or
        !          3372: for copying many scattered blocks of text into one place.
        !          3373: 
        !          3374:   You can accumulate blocks of text from scattered locations either into a
        !          3375: buffer or into a file if you like.  These commands are described here.  You
        !          3376: can also use Emacs registers for storing and accumulating text.
        !          3377: @xref{Registers}.
        !          3378: 
        !          3379: @table @kbd
        !          3380: @item C-x a
        !          3381: Append region to contents of specified buffer (@code{append-to-buffer}).
        !          3382: @item M-x prepend-to-buffer
        !          3383: Prepend region to contents of specified buffer.
        !          3384: @item M-x copy-to-buffer
        !          3385: Copy region into specified buffer, deleting that buffer's old contents.
        !          3386: @item M-x insert-buffer
        !          3387: Insert contents of specified buffer into current buffer at point.
        !          3388: @item M-x append-to-file
        !          3389: Append region to contents of specified file, at the end.
        !          3390: @end table
        !          3391: 
        !          3392:   To accumulate text into a buffer, use the command @kbd{C-x a @var{buffername}}
        !          3393: (@code{append-to-buffer}), which inserts a copy of the region into the
        !          3394: buffer @var{buffername}, at the location of point in that buffer.  If there
        !          3395: is no buffer with that name, one is created.  If you append text into a
        !          3396: buffer which has been used for editing, the copied text goes into the
        !          3397: middle of the text of the buffer, wherever point happens to be in it.
        !          3398: 
        !          3399:   Point in that buffer is left at the end of the copied text, so successive
        !          3400: uses of @kbd{C-x a} accumulate the text in the specified buffer in the same
        !          3401: order as they were copied.  Strictly speaking, @kbd{C-x a} does not always
        !          3402: append to the text already in the buffer; but if @kbd{C-x a} is the only
        !          3403: command used to alter a buffer, it does always append to the existing text
        !          3404: because point is always at the end.
        !          3405: 
        !          3406:   @kbd{M-x prepend-to-buffer} is just like @kbd{C-x a} except that point in
        !          3407: the other buffer is left before the copied text, so successive prependings
        !          3408: add text in reverse order.  @kbd{M-x copy-to-buffer} is similar except that
        !          3409: any existing text in the other buffer is deleted, so the buffer is left
        !          3410: containing just the text newly copied into it.
        !          3411: 
        !          3412:   You can retrieve the accumulated text from that buffer with @kbd{M-x
        !          3413: insert-buffer}; this too takes @var{buffername} as an argument.  It inserts
        !          3414: a copy of the text in buffer @var{buffername} into the selected buffer.
        !          3415: You could alternatively select the other buffer for editing, perhaps moving
        !          3416: text from it by killing or with @kbd{C-x a}.  @xref{Buffers}, for
        !          3417: background information on buffers.
        !          3418: 
        !          3419:   Instead of accumulating text within Emacs, in a buffer, you can append
        !          3420: text directly into a file with @kbd{M-x append-to-file}, which takes
        !          3421: @var{file-name} as an argument.  It adds the text of the region to the end
        !          3422: of the specified file.  The file is changed immediately on disk. This
        !          3423: command is normally used with files that are @i{not} being visited in
        !          3424: Emacs.  Using it on a file that Emacs is visiting can produce confusing
        !          3425: results, because the text inside Emacs for that file will not change
        !          3426: while the file itself changes.
        !          3427: 
        !          3428: @node Rectangles, Registers, Accumulating Text, Top
        !          3429: @section Rectangles
        !          3430: @cindex rectangles
        !          3431: 
        !          3432:   The rectangle commands affect rectangular areas of the text: all the
        !          3433: characters between a certain pair of columns, in a certain range of lines.
        !          3434: Commands are provided to kill rectangles, yank killed rectangles, clear
        !          3435: them out, or delete them.  Rectangle commands are useful with text in
        !          3436: multicolumnar formats, such as perhaps code with comments at the right,
        !          3437: or for changing text into or out of such formats.
        !          3438: 
        !          3439:   When you must specify a rectangle for a command to work on, you do
        !          3440: it by putting the mark at one corner and point at the opposite corner.
        !          3441: The rectangle thus specified is called the @dfn{region-rectangle}
        !          3442: because it is controlled about the same way the region is controlled.
        !          3443: But remember that a given combination of point and mark values can be
        !          3444: interpreted either as specifying a region or as specifying a
        !          3445: rectangle; it is up to the command that uses them to choose the
        !          3446: interpretation.
        !          3447: 
        !          3448: @table @kbd
        !          3449: @item M-x delete-rectangle
        !          3450: Delete the text of the region-rectangle, moving any following text on
        !          3451: each line leftward to the left edge of the region-rectangle.
        !          3452: @item M-x kill-rectangle
        !          3453: Similar, but also save the contents of the region-rectangle as the
        !          3454: ``last killed rectangle''.
        !          3455: @item M-x yank-rectangle
        !          3456: Yank the last killed rectangle with its upper left corner at point.
        !          3457: @item M-x open-rectangle
        !          3458: Insert blank space to fill the space of the region-rectangle.
        !          3459: The previous contents of the region-rectangle are pushed rightward.
        !          3460: @item M-x clear-rectangle
        !          3461: Clear the region-rectangle by replacing its contents with spaces.
        !          3462: @end table
        !          3463: 
        !          3464:   The rectangle operations fall into two classes: commands deleting and
        !          3465: moving rectangles, and commands for blank rectangles.
        !          3466: 
        !          3467: @findex delete-rectangle
        !          3468: @findex kill-rectangle
        !          3469:   There are two ways to get rid of the text in a rectangle: you can discard
        !          3470: the text (delete it) or save it as the ``last killed'' rectangle.  The
        !          3471: commands for these two ways are @kbd{M-x delete-rectangle} and @kbd{M-x
        !          3472: kill-rectangle}.  In either case, the portion of each line that falls inside
        !          3473: the rectangle's boundaries is deleted, causing following text (if any) on
        !          3474: the line to move left.
        !          3475: 
        !          3476:   Note that ``killing'' a rectangle is not killing in the usual sense; the
        !          3477: rectangle is not stored in the kill ring, but in a special place that
        !          3478: can only record the most recent rectangle killed.  This is because yanking
        !          3479: a rectangle is so different from yanking linear text that different yank
        !          3480: commands have to be used and yank-popping is hard to make sense of.
        !          3481: 
        !          3482:   Inserting a rectangle is the opposite of deleting one.  All you need to
        !          3483: specify is where to put the upper left corner; that is done by putting
        !          3484: point there.  The rectangle's first line is inserted there, the rectangle's
        !          3485: second line is inserted at a point one line vertically down, and so on.
        !          3486: The number of lines affected is determined by the height of the saved
        !          3487: rectangle.
        !          3488: 
        !          3489: @findex yank-rectangle
        !          3490:   To insert the last killed rectangle, type @kbd{M-x yank-rectangle}.
        !          3491: This can be used to convert single-column lists into double-column
        !          3492: lists; kill the second half of the list as a rectangle and then
        !          3493: yank it beside the first line of the list.
        !          3494: 
        !          3495: @findex open-rectangle
        !          3496: @findex clear-rectangle
        !          3497:   There are two commands for working with blank rectangles: @kbd{M-x
        !          3498: clear-rectangle} to blank out existing text, and @kbd{M-x open-rectangle}
        !          3499: to insert a blank rectangle.  Clearing a rectangle is equivalent to
        !          3500: deleting it and then inserting as blank rectangle of the same size.
        !          3501: 
        !          3502:   Rectangles can also be copied into and out of registers.
        !          3503: @xref{RegRect,,Rectangle Registers}.
        !          3504: 
        !          3505: @node Registers, Display, Rectangles, Top
        !          3506: @chapter Registers
        !          3507: @cindex registers
        !          3508: 
        !          3509:   Emacs @dfn{registers} are places you can save text or positions for
        !          3510: later use.  Text saved in a register can be copied into the buffer
        !          3511: once or many times; a position saved in a register is used by moving
        !          3512: point to that position.  Rectangles can also be copied into and out of
        !          3513: registers (@pxref{Rectangles}).
        !          3514: 
        !          3515:   Each register has a name, which is a single character.  A register can
        !          3516: store either a piece of text or a position or a rectangle, but only one
        !          3517: thing at any given time.  Whatever you store in a register remains
        !          3518: there until you store something else in that register.
        !          3519: 
        !          3520: @menu
        !          3521: * RegPos::    Saving positions in registers.
        !          3522: * RegText::   Saving text in registers.
        !          3523: * RegRect::   Saving rectangles in registers.
        !          3524: @end menu
        !          3525: 
        !          3526: @table @kbd
        !          3527: @item M-x view-register @key{RET} @var{r}
        !          3528: Display a description of what register @var{r} contains.
        !          3529: @end table
        !          3530: 
        !          3531: @findex view-register
        !          3532:   @kbd{M-x view-register} reads a register name as an argument and then
        !          3533: displays the contents of the specified register.
        !          3534: 
        !          3535: @node RegPos, RegText, Registers, Registers
        !          3536: @section Saving Positions in Registers
        !          3537: 
        !          3538:   Saving a position records a spot in a buffer so that you can move
        !          3539: back there later.  Moving to a saved position reselects the buffer
        !          3540: and moves point to the spot.
        !          3541: 
        !          3542: @table @kbd
        !          3543: @item C-x / @var{r}
        !          3544: Save location of point in register @var{r} (@code{point-to-register}).
        !          3545: @item C-x j @var{r}
        !          3546: Jump to the location saved in register @var{r} (@code{register-to-point}).
        !          3547: @end table
        !          3548: 
        !          3549: @kindex C-x /
        !          3550: @findex point-to-register
        !          3551:   To save the current location of point in a register, choose a name
        !          3552: @var{r} and type @kbd{C-x / @var{r}}.  The register @var{r} retains
        !          3553: the location thus saved until you store something else in that
        !          3554: register.@refill
        !          3555: 
        !          3556: @kindex C-x j
        !          3557: @findex register-to-point
        !          3558:   The command @kbd{C-x j @var{r}} moves point to the location recorded
        !          3559: in register @var{r}.  The register is not affected; it continues to
        !          3560: record the same location.  You can jump to the same position using the
        !          3561: same register any number of times.
        !          3562: 
        !          3563: @node RegText, RegRect, RegPos, Registers
        !          3564: @section Saving Text in Registers
        !          3565: 
        !          3566:   When you want to insert a copy of the same piece of text frequently, it
        !          3567: may be impractical to use the kill ring, since each subsequent kill moves
        !          3568: the piece of text further down on the ring.  It becomes hard to keep track
        !          3569: of what argument is needed to retrieve the same text with @kbd{C-y}.  An
        !          3570: alternative is to store the text in a register with @kbd{C-x x}
        !          3571: (@code{copy-to-register}) and then retrieve it with @kbd{C-x g}
        !          3572: (@code{insert-register}).
        !          3573: 
        !          3574: @table @kbd
        !          3575: @item C-x x @var{r}
        !          3576: Copy region into register @var{r} (@code{copy-to-register}).
        !          3577: @item C-x g @var{r}
        !          3578: Insert text contents of register @var{r} (@code{insert-register}).
        !          3579: @end table
        !          3580: 
        !          3581: @kindex C-x x
        !          3582: @kindex C-x g
        !          3583: @findex copy-to-register
        !          3584: @findex insert-register
        !          3585:   @kbd{C-x x @var{r}} stores a copy of the text of the region into the
        !          3586: register named @var{r}.  Given a numeric argument, @kbd{C-x x} deletes the
        !          3587: text from the buffer as well.
        !          3588: 
        !          3589:   @kbd{C-x g @var{r}} inserts in the buffer the text from register @var{r}.
        !          3590: Normally it leaves point before the text and places the mark after, but
        !          3591: with a numeric argument it puts point after the text and the mark before.
        !          3592: 
        !          3593: @node RegRect,, RegText, Registers
        !          3594: @section Saving Rectangles in Registers
        !          3595: 
        !          3596:   A register can contain a rectangle instead of linear text.  The rectangle
        !          3597: is represented as a list of strings.  @xref{Rectangles}, for basic
        !          3598: information on rectangles and how rectangles in the buffer are specified.
        !          3599: 
        !          3600: @table @kbd
        !          3601: @c !!! following generates acceptable underfull hbox
        !          3602: @item C-x r @var{r}
        !          3603: Copy the region-rectangle into register @var{r} (@code{copy-region-to-rectangle}).
        !          3604: With numeric argument, delete it as well.
        !          3605: @item C-x g @var{r}
        !          3606: Insert the rectangle stored in register @var{r} (if it contains a
        !          3607: rectangle) (@code{insert-register}).
        !          3608: @end table
        !          3609: 
        !          3610:   The @kbd{C-x g} command inserts linear text if the register contains
        !          3611: that, or inserts a rectangle if the register contains one.
        !          3612: 
        !          3613: @node Display, Search, Registers, Top
        !          3614: @chapter Controlling the Display
        !          3615: 
        !          3616:   Since only part of a large buffer fits in the window, Emacs tries to show
        !          3617: the part that is likely to be interesting.  The display control commands
        !          3618: allow you to specify which part of the text you want to see.
        !          3619: 
        !          3620: @table @kbd
        !          3621: @item C-l
        !          3622: Clear screen and redisplay, scrolling the selected window to center
        !          3623: point vertically within it (@code{recenter}).
        !          3624: @item C-v
        !          3625: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
        !          3626: @item M-v
        !          3627: Scroll backward (@code{scroll-down}).
        !          3628: @item @var{arg} C-l
        !          3629: Scroll so point is on line @var{arg} (@code{recenter}).
        !          3630: @item C-x <
        !          3631: Scroll text in current window to the left (@code{scroll-left}).
        !          3632: @item C-x >
        !          3633: Scroll to the right (@code{scroll-right}).
        !          3634: @item C-x $
        !          3635: Make deeply indented lines invisible (@code{set-selective-display}).
        !          3636: @end table
        !          3637: 
        !          3638: @menu
        !          3639: * Scrolling::             Moving text up and down in a window.
        !          3640: * Horizontal Scrolling::   Moving text left and right in a window.
        !          3641: * Selective Display::      Hiding lines with lots of indentation.
        !          3642: * Display Vars::           Information on variables for customizing display.
        !          3643: @end menu
        !          3644: 
        !          3645: @node Scrolling, Horizontal Scrolling, Display, Display
        !          3646: @section Scrolling
        !          3647: 
        !          3648:   If a buffer contains text that is too large to fit entirely within a
        !          3649: window that is displaying the buffer, Emacs shows a contiguous section of
        !          3650: the text.  The section shown always contains point.
        !          3651: 
        !          3652: @cindex scrolling
        !          3653:   @dfn{Scrolling} means moving text up or down in the window so that
        !          3654: different parts of the text are visible.  Scrolling forward means that text
        !          3655: moves up, and new text appears at the bottom.  Scrolling backward moves
        !          3656: text down and new text appears at the top.
        !          3657: 
        !          3658:   Scrolling happens automatically if you move point past the bottom or top
        !          3659: of the window.  You can also explicitly request scrolling with the commands
        !          3660: in this section.
        !          3661: 
        !          3662: @ifinfo
        !          3663: @table @kbd
        !          3664: @item C-l
        !          3665: Clear screen and redisplay, scrolling the selected window to center
        !          3666: point vertically within it (@code{recenter}).
        !          3667: @item C-v
        !          3668: Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}).
        !          3669: @item M-v
        !          3670: Scroll backward (@code{scroll-down}).
        !          3671: @item @var{arg} C-l
        !          3672: Scroll so point is on line @var{arg} (@code{recenter}).
        !          3673: @end table
        !          3674: @end ifinfo
        !          3675: 
        !          3676: @kindex C-l
        !          3677: @findex recenter
        !          3678:   The most basic scrolling command is @kbd{C-l} (@code{recenter}) with no
        !          3679: argument.  It clears the entire screen and redisplays all windows.  In
        !          3680: addition, the selected window is scrolled so that point is halfway down
        !          3681: from the top of the window.
        !          3682: 
        !          3683: @kindex C-v
        !          3684: @kindex M-v
        !          3685: @findex scroll-up
        !          3686: @findex scroll-down
        !          3687:   The scrolling commands @kbd{C-v} and @kbd{M-v} let you move all the text
        !          3688: in the window up or down a few lines.  @kbd{C-v} (@code{scroll-up}) with an
        !          3689: argument shows you that many more lines at the bottom of the window, moving
        !          3690: the text and point up together as @kbd{C-l} might.  @kbd{C-v} with a
        !          3691: negative argument shows you more lines at the top of the window.
        !          3692: @kbd{Meta-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the
        !          3693: opposite direction.@refill
        !          3694: 
        !          3695: @vindex next-screen-context-lines
        !          3696:   To read the buffer a windowful at a time, use @kbd{C-v} with no argument.
        !          3697: It takes the last two lines at the bottom of the window and puts them at
        !          3698: the top, followed by nearly a whole windowful of lines not previously
        !          3699: visible.  If point was in the text scrolled off the top, it moves to the
        !          3700: new top of the window.  @kbd{M-v} with no argument moves backward with
        !          3701: overlap similarly.  The number of lines of overlap across a @kbd{C-v} or
        !          3702: @kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by
        !          3703: default, it is two.
        !          3704: 
        !          3705:   Another way to do scrolling is with @kbd{C-l} with a numeric argument.
        !          3706: @kbd{C-l} does not clear the screen when given an argument; it only scrolls
        !          3707: the selected window.  With a positive argument @var{n}, it repositions text
        !          3708: to put point @var{n} lines down from the top.  An argument of zero puts
        !          3709: point on the very top line.  Point does not move with respect to the text;
        !          3710: rather, the text and point move rigidly on the screen.  @kbd{C-l} with a
        !          3711: negative argument puts point that many lines from the bottom of the window.
        !          3712: For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u
        !          3713: - 5 C-l} puts it five lines from the bottom.  Just @kbd{C-u} as argument,
        !          3714: as in @kbd{C-u C-l}, scrolls point to the center of the screen.
        !          3715: 
        !          3716: @vindex scroll-step
        !          3717:   Scrolling happens automatically if point has moved out of the visible
        !          3718: portion of the text when it is time to display.  Usually the scrolling is
        !          3719: done so as to put point vertically centered within the window.  However, if
        !          3720: the variable @code{scroll-step} has a nonzero value, an attempt is made to
        !          3721: scroll the buffer by that many lines; if that is enough to bring point back
        !          3722: into visibility, that is what is done.
        !          3723: 
        !          3724: @node Horizontal Scrolling,, Scrolling, Display
        !          3725: @section Horizontal Scrolling
        !          3726: 
        !          3727: @ifinfo
        !          3728: @table @kbd
        !          3729: @item C-x <
        !          3730: Scroll text in current window to the left (@code{scroll-left}).
        !          3731: @item C-x >
        !          3732: Scroll to the right (@code{scroll-right}).
        !          3733: @end table
        !          3734: @end ifinfo
        !          3735: 
        !          3736: @kindex C-x <
        !          3737: @kindex C-x >
        !          3738: @findex scroll-left
        !          3739: @findex scroll-right
        !          3740: @cindex horizontal scrolling
        !          3741:   The text in a window can also be scrolled horizontally.  This means that
        !          3742: each line of text is shifted sideways in the window, and one or more
        !          3743: characters at the beginning of each line are not displayed at all.  When a
        !          3744: window has been scrolled horizontally in this way, text lines are truncated
        !          3745: rather than continued (@pxref{Continuation Lines}), with a @samp{$} appearing
        !          3746: in the first column when there is text truncated to the left, and in the
        !          3747: last column when there is text truncated to the right.
        !          3748: 
        !          3749:   The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected window
        !          3750: to the left by @var{n} columns with argument @var{n}.  With no argument, it scrolls
        !          3751: by almost the full width of the window (two columns less, to be precise).
        !          3752: @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right.
        !          3753: The window cannot be scrolled any farther to the right once it is
        !          3754: displaying normally (with each line starting at the window's left margin);
        !          3755: attempting to do so has no effect.
        !          3756: 
        !          3757: @node Selective Display, Display Vars, Display, Display
        !          3758: @section Selective Display
        !          3759: @findex set-selective-display
        !          3760: @kindex C-x $
        !          3761: 
        !          3762:   Emacs has the ability to hide lines indented more than a certain number
        !          3763: of columns (you specify how many columns).  You can use this to get an
        !          3764: overview of a part of a program.
        !          3765: 
        !          3766:   To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a
        !          3767: numeric argument @var{n}.  (@xref{Arguments}, for how to give the
        !          3768: argument.)  Then lines with at least @var{n} columns of indentation
        !          3769: disappear from the screen.  The only indication of their presence is that
        !          3770: three dots (@samp{@dots{}}) appear at the end of each visible line that is
        !          3771: followed by one or more invisible ones.@refill
        !          3772: 
        !          3773:   The invisible lines are still present in the buffer, and most editing
        !          3774: commands see them as usual, so it is very easy to put point in the middle
        !          3775: of invisible text.  When this happens, the cursor appears at the end of the
        !          3776: previous line, after the three dots.  If point is at the end of the visible
        !          3777: line, before the newline that ends it, the cursor appears before the three
        !          3778: dots.
        !          3779: 
        !          3780:   The commands @kbd{C-n} and @kbd{C-p} move across the invisible lines as if they
        !          3781: were not there.
        !          3782: 
        !          3783:   To make everything visible again, type @kbd{C-x $} with no argument.
        !          3784: 
        !          3785: @node Display Vars,, Selective Display, Display
        !          3786: @section Variables Controlling Display
        !          3787: 
        !          3788:   This section contains information for customization only.  Beginning
        !          3789: users should skip it.
        !          3790: 
        !          3791: @vindex mode-line-inverse-video
        !          3792:   The variable @code{mode-line-inverse-video} controls whether the mode
        !          3793: line is displayed in inverse video (assuming the terminal supports it);
        !          3794: @code{nil} means don't do so.  @xref{Mode Line}.
        !          3795: 
        !          3796: @vindex inverse-video
        !          3797:   If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts
        !          3798: to invert all the lines of the display from what they normally are.
        !          3799: 
        !          3800: @vindex visible-bell
        !          3801:   If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
        !          3802: to make the whole screen blink when it would normally make an audible bell
        !          3803: sound.  This variable has no effect if your terminal does not have a way
        !          3804: to make the screen blink.@refill
        !          3805: 
        !          3806: @vindex no-redraw-on-reenter
        !          3807:   When you reenter Emacs after suspending, Emacs normally clears the screen
        !          3808: and redraws the entire display.  On some terminals with more than one page
        !          3809: of memory, it is possible to arrange the termcap entry so that the
        !          3810: @samp{ti} and @samp{te} strings (output to the terminal when Emacs is
        !          3811: entered and exited, respectively) switch between pages of memory so as to
        !          3812: use one page for Emacs and another page for other output.  Then you might
        !          3813: want to set the variable @code{no-redraw-on-reenter} non-@code{nil} so that
        !          3814: Emacs will assume, when resumed, that the screen page it is using still
        !          3815: contains what Emacs last wrote there.
        !          3816: 
        !          3817: @vindex echo-keystrokes
        !          3818:   The variable @code{echo-keystrokes} controls the echoing of multi-character
        !          3819: keys; its value is the number of seconds of pause required to cause echoing
        !          3820: to start, or zero meaning don't echo at all.  @xref{Echo Area}.
        !          3821: 
        !          3822: @vindex ctl-arrow
        !          3823:   If the variable @code{ctl-arrow} is @code{nil}, control characters in the
        !          3824: buffer are displayed with octal escape sequences, all except newline and
        !          3825: tab.  Altering the value of @code{ctl-arrow} makes it local to the current
        !          3826: buffer; until that time, the default value is in effect.  The default is
        !          3827: initially @code{t}.  @xref{Locals}.
        !          3828: 
        !          3829: @vindex tab-width
        !          3830:   Normally, a tab character in the buffer is displayed as whitespace which
        !          3831: extends to the next display tab stop position, and display tab stops come
        !          3832: at intervals equal to eight spaces.  The number of spaces per tab is
        !          3833: controlled by the variable @code{tab-width}, which is made local by
        !          3834: changing it, just like @code{ctl-arrow}.  Note that how the tab character
        !          3835: in the buffer is displayed has nothing to do with the definition of
        !          3836: @key{TAB} as a command.
        !          3837: 
        !          3838: @vindex selective-display-ellipses
        !          3839:   If you set the variable @code{selective-display-ellipses} to @code{nil},
        !          3840: the three dots do not appear at the end of a line that precedes invisible
        !          3841: lines.  Then there is no visible indication of the invisible lines.
        !          3842: This variable too becomes local automatically when set.
        !          3843: 
        !          3844: @node Search, Fixit, Display, Top
        !          3845: @chapter Searching and Replacement
        !          3846: @cindex searching
        !          3847: 
        !          3848:   Like other editors, Emacs has commands for searching for occurrences of
        !          3849: a string.  The principal search command is unusual in that it is
        !          3850: @dfn{incremental}; it begins to search before you have finished typing the
        !          3851: search string.  There are also nonincremental search commands more like
        !          3852: those of other editors.
        !          3853: 
        !          3854:   Besides the usual @code{replace-string} command that finds all
        !          3855: occurrences of one string and replaces them with another, Emacs has a fancy
        !          3856: replacement command called @code{query-replace} which asks interactively
        !          3857: which occurrences to replace.
        !          3858: 
        !          3859: @menu
        !          3860: * Incremental Search::     Search happens as you type the string.
        !          3861: * Nonincremental Search::  Specify entire string and then search.
        !          3862: * Word Search::            Search for sequence of words.
        !          3863: * Regexp Search::          Search for match for a regexp.
        !          3864: * Regexps::                Syntax of regular expressions.
        !          3865: * Search Case::            To ignore case while searching, or not.
        !          3866: * Replace::                Search, and replace some or all matches.
        !          3867: * Other Repeating Search:: Operating on all matches for some regexp.
        !          3868: @end menu
        !          3869: 
        !          3870: @node Incremental Search, Nonincremental Search, Search, Search
        !          3871: @section Incremental Search
        !          3872: 
        !          3873:   An incremental search begins searching as soon as you type the first
        !          3874: character of the search string.  As you type in the search string, Emacs
        !          3875: shows you where the string (as you have typed it so far) would be found.
        !          3876: When you have typed enough characters to identify the place you want, you
        !          3877: can stop.  Depending on what you will do next, you may or may not need to
        !          3878: terminate the search explicitly with an @key{ESC} first.
        !          3879: 
        !          3880: @c WideCommands
        !          3881: @table @kbd
        !          3882: @item C-s
        !          3883: Incremental search forward (@code{isearch-forward}).
        !          3884: @item C-r
        !          3885: Incremental search backward (@code{isearch-backward}).
        !          3886: @end table
        !          3887: 
        !          3888: @kindex C-s
        !          3889: @kindex C-r
        !          3890: @findex isearch-forward
        !          3891: @findex isearch-backward
        !          3892:   @kbd{C-s} starts an incremental search.  @kbd{C-s} reads characters from
        !          3893: the keyboard and positions the cursor at the first occurrence of the
        !          3894: characters that you have typed.  If you type @kbd{C-s} and then @kbd{F},
        !          3895: the cursor moves right after the first @samp{F}.  Type an @kbd{O}, and see
        !          3896: the cursor move to after the first @samp{FO}.  After another @kbd{O}, the
        !          3897: cursor is after the first @samp{FOO} after the place where you started the
        !          3898: search.  Meanwhile, the search string @samp{FOO} has been echoed in the
        !          3899: echo area.@refill
        !          3900: 
        !          3901:   The echo area display ends with three dots when actual searching is going
        !          3902: on.  When search is waiting for more input, the three dots are removed.
        !          3903: (On slow terminals, the three dots are not displayed.)
        !          3904: 
        !          3905:   If you make a mistake in typing the search string, you can erase
        !          3906: characters with @key{DEL}.  Each @key{DEL} cancels the last character of
        !          3907: search string.  This does not happen until Emacs is ready to read another
        !          3908: input character; first it must either find, or fail to find, the character
        !          3909: you want to erase.  If you do not want to wait for this to happen, use
        !          3910: @kbd{C-g} as described below.@refill
        !          3911: 
        !          3912:   When you are satisfied with the place you have reached, you can type
        !          3913: @key{ESC}, which stops searching, leaving the cursor where the search
        !          3914: brought it.  Also, any command not specially meaningful in searches stops
        !          3915: the searching and is then executed.  Thus, typing @kbd{C-a} would exit the
        !          3916: search and then move to the beginning of the line.  @key{ESC} is necessary
        !          3917: only if the next command you want to type is a printing character,
        !          3918: @key{DEL}, @key{ESC}, or another control character that is special within
        !          3919: searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s} or @kbd{C-y}).
        !          3920: 
        !          3921:   Sometimes you search for @samp{FOO} and find it, but not the one you
        !          3922: expected to find.  There was a second @samp{FOO} that you forgot about,
        !          3923: before the one you were looking for.  In this event, type another @kbd{C-s}
        !          3924: to move to the next occurrence of the search string.  This can be done any
        !          3925: number of times.  If you overshoot, you can cancel some @kbd{C-s}
        !          3926: characters with @key{DEL}.
        !          3927: 
        !          3928:   After you exit a search, you can search for the same string again by
        !          3929: typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
        !          3930: incremental search, and the second @kbd{C-s} means ``search again''.
        !          3931: 
        !          3932:   If your string is not found at all, the echo area says @samp{Failing
        !          3933: I-Search}.  The cursor is after the place where Emacs found as much of your
        !          3934: string as it could.  Thus, if you search for @samp{FOOT}, and there is no
        !          3935: @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
        !          3936: At this point there are several things you can do.  If your string was
        !          3937: mistyped, you can rub some of it out and correct it.  If you like the place
        !          3938: you have found, you can type @key{ESC} or some other Emacs command to
        !          3939: ``accept what the search offered''.  Or you can type @kbd{C-g}, which
        !          3940: removes from the search string the characters that could not be found (the
        !          3941: @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
        !          3942: @samp{FOOT}).  A second @kbd{C-g} at that point cancels the search
        !          3943: entirely, returning point to where it was when the search started.
        !          3944: 
        !          3945:   If a search is failing and you ask to repeat it by typing another
        !          3946: @kbd{C-s}, it starts again from the beginning of the buffer.  Repeating
        !          3947: a failing reverse search with @kbd{C-r} starts again from the end.  This
        !          3948: is called @dfn{wrapping around}.  @samp{Wrapped} appears in the search
        !          3949: prompt once this has happened.
        !          3950: 
        !          3951: @cindex quitting (in search)
        !          3952:   The @kbd{C-g} ``quit'' character does special things during searches;
        !          3953: just what it does depends on the status of the search.  If the search has
        !          3954: found what you specified and is waiting for input, @kbd{C-g} cancels the
        !          3955: entire search.  The cursor moves back to where you started the search.  If
        !          3956: @kbd{C-g} is typed when there are characters in the search string that have
        !          3957: not been found---because Emacs is still searching for them, or because it
        !          3958: has failed to find them---then the search string characters which have not
        !          3959: been found are discarded from the search string.  With them gone, the
        !          3960: search is now successful and waiting for more input, so a second @kbd{C-g}
        !          3961: will cancel the entire search.
        !          3962: 
        !          3963:   To search for a control character such as @kbd{C-s} or @key{DEL} or
        !          3964: @key{ESC}, you must quote it by typing @kbd{C-q} first.  This function
        !          3965: of @kbd{C-q} is analogous to its meaning as an Emacs command: it causes
        !          3966: the following character to be treated the way a graphic character would
        !          3967: normally be treated in the same context.  You can also specify a quoted
        !          3968: character in octal while searching, just as you can for insertion.  
        !          3969: @xref{Basic}.
        !          3970: 
        !          3971:   You can change to searching backwards with @kbd{C-r}.  If a search fails
        !          3972: because the place you started was too late in the file, you should do this.
        !          3973: Repeated @w{@kbd{C-r}} keeps looking for more occurrences backwards.  A
        !          3974: @kbd{C-s} starts going forwards again.  @kbd{C-r} in a search can be cancelled
        !          3975: with @key{DEL}.
        !          3976: 
        !          3977:   If you know initially that you want to search backwards, you can
        !          3978: use @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r}
        !          3979: is also a key running a command (@code{isearch-backward}) to search
        !          3980: backward.
        !          3981: 
        !          3982:   The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search
        !          3983: to grab text from the buffer into the search string.  This makes it
        !          3984: convenient to search for another occurrence of text at point.  @kbd{C-w}
        !          3985: copies the word after point as part of the search string, advancing
        !          3986: point over that word.  Another @kbd{C-s} to repeat the search will then
        !          3987: search for a string including that word.  @kbd{C-y} is similar to @kbd{C-w}
        !          3988: but copies all the rest of the current line into the search string.
        !          3989: 
        !          3990:   All the characters special in incremental search can be changed by setting
        !          3991: the following variables:
        !          3992: 
        !          3993: @vindex search-delete-char
        !          3994: @vindex search-exit-char
        !          3995: @vindex search-quote-char
        !          3996: @vindex search-repeat-char
        !          3997: @vindex search-reverse-char
        !          3998: @vindex search-yank-line-char
        !          3999: @vindex search-yank-word-char
        !          4000: @table @code
        !          4001: @item search-delete-char
        !          4002: Character to delete from incremental search string (normally @key{DEL}).
        !          4003: @item search-exit-char
        !          4004: Character to exit incremental search (normally @key{ESC}).
        !          4005: @item search-quote-char
        !          4006: Character to quote special characters for incremental search (normally
        !          4007: @kbd{C-q}).
        !          4008: @item search-repeat-char
        !          4009: Character to repeat incremental search forwards (normally @w{@kbd{C-s}}).
        !          4010: @item search-reverse-char
        !          4011: Character to repeat incremental search backwards (normally @w{@kbd{C-r}}).
        !          4012: @item search-yank-line-char
        !          4013: Character to pull rest of line from buffer into search string
        !          4014: (normally @kbd{C-y}).
        !          4015: @item search-yank-word-char
        !          4016: Character to pull next word from buffer into search string (normally
        !          4017: @kbd{C-w}).
        !          4018: @end table
        !          4019: 
        !          4020: @subsection Slow Terminal Incremental Search
        !          4021: 
        !          4022:   Incremental search on a slow terminal uses a modified style of display
        !          4023: that is designed to take less time.  Instead of redisplaying the buffer at
        !          4024: each place the search gets to, it creates a new single-line window and uses
        !          4025: that to display the line that the search has found.  The single-line window
        !          4026: comes into play as soon as point gets outside of the text that is already
        !          4027: on the screen.
        !          4028: 
        !          4029:   When the search is terminated, the single-line window is removed.  Only
        !          4030: at this time is the window in which the search was done redisplayed to show
        !          4031: its new value of point.
        !          4032: 
        !          4033:   The three dots at the end of the search string, normally used to indicate
        !          4034: that searching is going on, are not displayed in slow style display.
        !          4035: 
        !          4036: @vindex search-slow-speed
        !          4037:   The slow terminal style of display is used when the terminal baud rate is
        !          4038: less than or equal to the value of the variable @code{search-slow-speed},
        !          4039: initially 1200.
        !          4040: 
        !          4041: @vindex search-slow-window-lines
        !          4042:   The number of lines to use in slow terminal search display is controlled
        !          4043: by the variable @code{search-slow-window-lines}.  1 is its normal value.
        !          4044: 
        !          4045: @node Nonincremental Search, Word Search, Incremental Search, Search
        !          4046: @section Nonincremental Search
        !          4047: @cindex nonincremental search
        !          4048: 
        !          4049:   Emacs also has conventional nonincremental search commands, which require
        !          4050: you to type the entire search string before searching begins.
        !          4051: 
        !          4052: @table @kbd
        !          4053: @item C-s @key{ESC} @var{string} @key{RET}
        !          4054: Search for @var{string}.
        !          4055: @item C-r @key{ESC} @var{string} @key{RET}
        !          4056: Search backward for @var{string}.
        !          4057: @end table
        !          4058: 
        !          4059:   To do a nonincremental search, first type @kbd{C-s @key{ESC}}.  This
        !          4060: enters the minibuffer to read the search string; terminate the string with
        !          4061: @key{RET}, and then the search is done.  If the string is not found the
        !          4062: search command gets an error.
        !          4063: 
        !          4064:   The way @kbd{C-s @key{ESC}} works is that the @kbd{C-s} invokes
        !          4065: incremental search, which is specially programmed to invoke nonincremental
        !          4066: search if the argument you give it is empty.  (Such an empty argument would
        !          4067: otherwise be useless.)  @kbd{C-r @key{ESC}} also works this way.
        !          4068: 
        !          4069: @findex search-forward
        !          4070: @findex search-backward
        !          4071:   Forward and backward nonincremental searches are implemented by the
        !          4072: commands @code{search-forward} and @code{search-backward}.  These commands
        !          4073: may be bound to keys in the usual manner.  The reason that incremental
        !          4074: search is programmed to invoke them as well is that @kbd{C-s @key{ESC}}
        !          4075: is the traditional sequence of characters used in Emacs to invoke
        !          4076: nonincremental search.
        !          4077: 
        !          4078:   However, nonincremental searches performed using @kbd{C-s @key{ESC}} do
        !          4079: not call @code{search-forward} right away.  The first thing done is to see
        !          4080: if the next character is @kbd{C-w}, which requests a word search.
        !          4081: @ifinfo
        !          4082: @xref{Word Search}.
        !          4083: @end ifinfo
        !          4084: 
        !          4085: @node Word Search, Regexp Search, Nonincremental Search, Search
        !          4086: @section Word Search
        !          4087: @cindex word search
        !          4088: 
        !          4089:   Word search searches for a sequence of words without regard to how the
        !          4090: words are separated.  More precisely, you type a string of many words,
        !          4091: using single spaces to separate them, and the string can be found even if
        !          4092: there are multiple spaces, newlines or other punctuation between the words.
        !          4093: 
        !          4094:   Word search is useful in editing documents formatted by text formatters.
        !          4095: If you edit while looking at the printed, formatted version, you can't tell
        !          4096: where the line breaks are in the source file.  With word search, you can
        !          4097: search without having to know them.
        !          4098: 
        !          4099: @table @kbd
        !          4100: @item C-s @key{ESC} C-w @var{words} @key{RET}
        !          4101: Search for @var{words}, ignoring differences in punctuation.
        !          4102: @item C-r @key{ESC} C-w @var{words} @key{RET}
        !          4103: Search backward for @var{words}, ignoring differences in punctuation.
        !          4104: @end table
        !          4105: 
        !          4106:   Word search is a special case of nonincremental search and is invoked
        !          4107: with @kbd{C-s @key{ESC} C-w}.  This is followed by the search string, which
        !          4108: must always be terminated with @key{RET}.  Being nonincremental, this
        !          4109: search does not start until the argument is terminated.  It works by
        !          4110: constructing a regular expression and searching for that.  @xref{Regexp
        !          4111: Search}.
        !          4112: 
        !          4113:   A backward word search can be done by @kbd{C-r @key{ESC} C-w}.
        !          4114: 
        !          4115: @findex word-search-forward
        !          4116: @findex word-search-backward
        !          4117:   Forward and backward word searches are implemented by the commands
        !          4118: @code{word-search-forward} and @code{word-search-backward}.  These commands
        !          4119: may be bound to keys in the usual manner.  The reason that incremental
        !          4120: search is programmed to invoke them as well is that @kbd{C-s @key{ESC} C-w}
        !          4121: is the traditional Emacs sequence of keys for word search.
        !          4122: 
        !          4123: @node Regexp Search, Regexps, Word Search, Search
        !          4124: @section Regular Expression Search
        !          4125: @cindex regular expression
        !          4126: @cindex expressions, regular
        !          4127: @cindex regexp
        !          4128: 
        !          4129:   A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
        !          4130: denotes a set of strings, possibly an infinite set.  Searching for matches
        !          4131: for a regexp is a very powerful operation that editors on Unix systems have
        !          4132: traditionally offered.  In GNU Emacs, you can search for the next match for
        !          4133: a regexp either incrementally or not.
        !          4134: 
        !          4135: @kindex C-M-s
        !          4136: @findex isearch-forward-regexp
        !          4137: @findex isearch-backward-regexp
        !          4138:   Incremental search for a regexp is done by typing @kbd{C-M-s}
        !          4139: (@code{isearch-forward-regexp}).  This command reads a search string
        !          4140: incrementally just like @kbd{C-s}, but it treats the search string as a
        !          4141: regexp rather than looking for an exact match against the text in the
        !          4142: buffer.  Each time you add text to the search string, you make the regexp
        !          4143: longer, and the new regexp is searched for.  A reverse regexp search command,
        !          4144: @code{isearch-backward-regexp}, also exists but no key runs it.
        !          4145: 
        !          4146:   All of the control characters that do special things within an ordinary
        !          4147: incremental search have the same function in incremental regexp search.
        !          4148: Typing @kbd{C-s} or @kbd{C-r} immediately after starting the search
        !          4149: retrieves the last incremental search regexp used; that is to say,
        !          4150: incremental regexp and non-regexp searches have independent defaults.
        !          4151: 
        !          4152:   Note that adding characters to the regexp in an incremental regexp search
        !          4153: does not make the cursor move back and start again.  Perhaps it ought to; I
        !          4154: am not sure.  As it stands, if you have searched for @samp{foo} and you
        !          4155: add @samp{\|bar}, the search will not check for a @samp{bar} in the
        !          4156: buffer before the @samp{foo}.
        !          4157: 
        !          4158: @findex re-search-forward
        !          4159: @findex re-search-backward
        !          4160:   Nonincremental search for a regexp is done by the functions
        !          4161: @code{re-search-forward} and @code{re-search-backward}.  You can invoke
        !          4162: these with @kbd{M-x}, or bind them to keys.  Also, you can call
        !          4163: @code{re-search-forward} by way of incremental regexp search with
        !          4164: @kbd{C-M-s @key{ESC}}.
        !          4165: 
        !          4166: @node Regexps, Search Case, Regexp Search, Search
        !          4167: @section Syntax of Regular Expressions
        !          4168: 
        !          4169: Regular expressions have a syntax in which a few characters are special
        !          4170: constructs and the rest are @dfn{ordinary}.  An ordinary character is a
        !          4171: simple regular expression which matches that character and nothing else.
        !          4172: The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
        !          4173: @samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special
        !          4174: characters will be defined.  Any other character appearing in a regular
        !          4175: expression is ordinary, unless a @samp{\} precedes it.@refill
        !          4176: 
        !          4177: For example, @samp{f} is not a special character, so it is ordinary, and
        !          4178: therefore @samp{f} is a regular expression that matches the string @samp{f}
        !          4179: and no other string.  (It does @i{not} match the string @samp{ff}.)  Likewise,
        !          4180: @samp{o} is a regular expression that matches only @samp{o}.@refill
        !          4181: 
        !          4182: Any two regular expressions @var{a} and @var{b} can be concatenated.  The
        !          4183: result is a regular expression which matches a string if @var{a} matches
        !          4184: some amount of the beginning of that string and @var{b} matches the rest of
        !          4185: the string.@refill
        !          4186: 
        !          4187: As a simple example, we can concatenate the regular expressions @samp{f}
        !          4188: and @samp{o} to get the regular expression @samp{fo}, which matches only
        !          4189: the string @samp{fo}.  Still trivial.  To do something nontrivial, you
        !          4190: need to use one of the special characters.  Here is a list of them.
        !          4191: 
        !          4192: @table @kbd
        !          4193: @item .@: @r{(Period)}
        !          4194: is a special character that matches any single character except a newline.
        !          4195: Using concatenation, we can make regular expressions like @samp{a.b} which
        !          4196: matches any three-character string which begins with @samp{a} and ends with
        !          4197: @samp{b}.@refill
        !          4198: 
        !          4199: @item *
        !          4200: is not a construct by itself; it is a suffix, which means the
        !          4201: preceding regular expression is to be repeated as many times as
        !          4202: possible.  In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
        !          4203: @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s.
        !          4204: The case of zero @samp{o}s is allowed: @samp{fo*} does match
        !          4205: @samp{f}.@refill
        !          4206: 
        !          4207: @samp{*} always applies to the @i{smallest} possible preceding
        !          4208: expression.  Thus, @samp{fo*} has a repeating @samp{o}, not a
        !          4209: repeating @samp{fo}.@refill
        !          4210: 
        !          4211: The matcher processes a @samp{*} construct by matching, immediately,
        !          4212: as many repetitions as can be found.  Then it continues with the rest
        !          4213: of the pattern.  If that fails, backtracking occurs, discarding some
        !          4214: of the matches of the @samp{*}-modified construct in case that makes
        !          4215: it possible to match the rest of the pattern.  For example, matching
        !          4216: @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
        !          4217: tries to match all three @samp{a}s; but the rest of the pattern is
        !          4218: @samp{ar} and there is only @samp{r} left to match, so this try fails.
        !          4219: The next alternative is for @samp{a*} to match only two @samp{a}s.
        !          4220: With this choice, the rest of the regexp matches successfully.@refill
        !          4221: 
        !          4222: @item +
        !          4223: Is a suffix character similar to @samp{*} except that it requires that
        !          4224: the preceding expression be matched at least once.  So, for example,
        !          4225: @samp{ca+r} will match the strings @samp{car} and @samp{caaaar}
        !          4226: but not the string @samp{cr}, whereas @samp{ca*r} would match all
        !          4227: three strings.@refill
        !          4228: 
        !          4229: @item ?
        !          4230: Is a suffix character similar to @samp{*} except that it can match the
        !          4231: preceding expression either once or not at all.  For example,
        !          4232: @samp{ca?r} will match @samp{car} or @samp{cr}; nothing else.
        !          4233: 
        !          4234: @item [ @dots{} ]
        !          4235: @samp{[} begins a @dfn{character set}, which is terminated by a
        !          4236: @samp{]}.  In the simplest case, the characters between the two form
        !          4237: the set.  Thus, @samp{[ad]} matches either one @samp{a} or one
        !          4238: @samp{d}, and @samp{[ad]*} matches any string composed of just
        !          4239: @samp{a}s and @samp{d}s (including the empty string), from which it
        !          4240: follows that @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
        !          4241: @samp{caddaar}, etc.@refill
        !          4242: 
        !          4243: Character ranges can also be included in a character set, by writing
        !          4244: two characters with a @samp{-} between them.  Thus, @samp{[a-z]}
        !          4245: matches any lower-case letter.  Ranges may be intermixed freely with
        !          4246: individual characters, as in @samp{[a-z$%.]}, which matches any lower
        !          4247: case letter or @samp{$}, @samp{%} or period.@refill
        !          4248: 
        !          4249: Note that the usual special characters are not special any more inside
        !          4250: a character set.  A completely different set of special characters
        !          4251: exists inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
        !          4252: 
        !          4253: To include a @samp{]} in a character set, you must make it the first
        !          4254: character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To
        !          4255: include a @samp{-}, write @samp{---}, which is a range containing only
        !          4256: @samp{-}.  To include @samp{^}, make it other than the first character
        !          4257: in the set.@refill
        !          4258: 
        !          4259: @item [^ @dots{} ]
        !          4260: @samp{[^} begins a @dfn{complement character set}, which matches any
        !          4261: character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]}
        !          4262: matches all characters @i{except} letters and digits.@refill
        !          4263: 
        !          4264: @samp{^} is not special in a character set unless it is the first
        !          4265: character.  The character following the @samp{^} is treated as if it
        !          4266: were first (@samp{-} and @samp{]} are not special there).
        !          4267: 
        !          4268: Note that a complement character set can match a newline, unless
        !          4269: newline is mentioned as one of the characters not to match.
        !          4270: 
        !          4271: @item ^
        !          4272: is a special character that matches the empty string, but only if at
        !          4273: the beginning of a line in the text being matched.  Otherwise it fails
        !          4274: to match anything.  Thus, @samp{^foo} matches a @samp{foo} which occurs
        !          4275: at the beginning of a line.
        !          4276: 
        !          4277: @item $
        !          4278: is similar to @samp{^} but matches only at the end of a line.  Thus,
        !          4279: @samp{xx*$} matches a string of one @samp{x} or more at the end of a line.
        !          4280: 
        !          4281: @item \
        !          4282: has two functions: it quotes the special characters (including
        !          4283: @samp{\}), and it introduces additional special constructs.
        !          4284: 
        !          4285: Because @samp{\} quotes special characters, @samp{\$} is a regular
        !          4286: expression which matches only @samp{$}, and @samp{\[} is a regular
        !          4287: expression which matches only @samp{[}, and so on.@refill
        !          4288: @end table
        !          4289: 
        !          4290: Note: for historical compatibility, special characters are treated as
        !          4291: ordinary ones if they are in contexts where their special meanings make no
        !          4292: sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
        !          4293: no preceding expression on which the @samp{*} can act.  It is poor practice
        !          4294: to depend on this behavior; better to quote the special character anyway,
        !          4295: regardless of where is appears.@refill
        !          4296: 
        !          4297: For the most part, @samp{\} followed by any character matches only
        !          4298: that character.  However, there are several exceptions: characters
        !          4299: which, when preceded by @samp{\}, are special constructs.  Such
        !          4300: characters are always ordinary when encountered on their own.  Here
        !          4301: is a table of @samp{\} constructs.
        !          4302: 
        !          4303: @table @kbd
        !          4304: @item \|
        !          4305: specifies an alternative.
        !          4306: Two regular expressions @var{a} and @var{b} with @samp{\|} in
        !          4307: between form an expression that matches anything that either @var{a} or
        !          4308: @var{b} will match.@refill
        !          4309: 
        !          4310: Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
        !          4311: but no other string.@refill
        !          4312: 
        !          4313: @samp{\|} applies to the largest possible surrounding expressions.  Only a
        !          4314: surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
        !          4315: @samp{\|}.@refill
        !          4316: 
        !          4317: Full backtracking capability exists to handle multiple uses of @samp{\|}.
        !          4318: 
        !          4319: @item \( @dots{} \)
        !          4320: is a grouping construct that serves three purposes:
        !          4321: 
        !          4322: @enumerate
        !          4323: @item
        !          4324: To enclose a set of @samp{\|} alternatives for other operations.
        !          4325: Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
        !          4326: 
        !          4327: @item
        !          4328: To enclose a complicated expression for the postfix @samp{*} to operate on.
        !          4329: Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any (zero or
        !          4330: more) number of @samp{na} strings.@refill
        !          4331: 
        !          4332: @item
        !          4333: To mark a matched substring for future reference.
        !          4334: 
        !          4335: @end enumerate
        !          4336: 
        !          4337: This last application is not a consequence of the idea of a
        !          4338: parenthetical grouping; it is a separate feature which happens to be
        !          4339: assigned as a second meaning to the same @samp{\( @dots{} \)} construct
        !          4340: because there is no conflict in practice between the two meanings.
        !          4341: Here is an explanation of this feature:
        !          4342: 
        !          4343: @item \@var{digit}
        !          4344: after the end of a @samp{\( @dots{} \)} construct, the matcher remembers the
        !          4345: beginning and end of the text matched by that construct.  Then, later on
        !          4346: in the regular expression, you can use @samp{\} followed by @var{digit}
        !          4347: to mean ``match the same text matched the @var{digit}'th time by the
        !          4348: @samp{\( @dots{} \)} construct.''@refill
        !          4349: 
        !          4350: The strings matching the first nine @samp{\( @dots{} \)} constructs appearing
        !          4351: in a regular expression are assigned numbers 1 through 9 in order that the
        !          4352: open-parentheses appear in the regular expression.  @samp{\1} through
        !          4353: @samp{\9} may be used to refer to the text matched by the corresponding
        !          4354: @samp{\( @dots{} \)} construct.
        !          4355: 
        !          4356: For example, @samp{\(.*\)\1} matches any newline-free string that is
        !          4357: composed of two identical halves.  The @samp{\(.*\)} matches the first
        !          4358: half, which may be anything, but the @samp{\1} that follows must match
        !          4359: the same exact text.
        !          4360: 
        !          4361: @item \`
        !          4362: matches the empty string, provided it is at the beginning
        !          4363: of the buffer.
        !          4364: 
        !          4365: @item \'
        !          4366: matches the empty string, provided it is at the end of
        !          4367: the buffer.
        !          4368: 
        !          4369: @item \b
        !          4370: matches the empty string, provided it is at the beginning or
        !          4371: end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
        !          4372: @samp{foo} as a separate word.  @samp{\bballs?\b} matches
        !          4373: @samp{ball} or @samp{balls} as a separate word.@refill
        !          4374: 
        !          4375: @item \B
        !          4376: matches the empty string, provided it is @i{not} at the beginning or
        !          4377: end of a word.
        !          4378: 
        !          4379: @item \<
        !          4380: matches the empty string, provided it is at the beginning of a word.
        !          4381: 
        !          4382: @item \>
        !          4383: matches the empty string, provided it is at the end of a word.
        !          4384: 
        !          4385: @item \w
        !          4386: matches any word-constituent character.  The editor syntax table
        !          4387: determines which characters these are.
        !          4388: 
        !          4389: @item \W
        !          4390: matches any character that is not a word-constituent.
        !          4391: 
        !          4392: @item \s@var{code}
        !          4393: matches any character whose syntax is @var{code}.  @var{code} is a
        !          4394: character which represents a syntax code: thus, @samp{w} for word
        !          4395: constituent, @samp{-} for whitespace, @samp{(} for open-parenthesis,
        !          4396: etc.  @xref{Syntax}.@refill
        !          4397: 
        !          4398: @item \S@var{code}
        !          4399: matches any character whose syntax is not @var{code}.
        !          4400: @end table
        !          4401: 
        !          4402:   Here is a complicated regexp, used by Emacs to recognize the end of a
        !          4403: sentence together with any whitespace that follows.  It is given in Lisp
        !          4404: syntax to enable you to distinguish the spaces from the tab characters.  In
        !          4405: Lisp syntax, the string constant begins and ends with a double-quote.
        !          4406: @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
        !          4407: backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
        !          4408: newline.
        !          4409: 
        !          4410: @example
        !          4411: "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
        !          4412: @end example
        !          4413: 
        !          4414: @noindent
        !          4415: This contains four parts in succession: a character set matching period,
        !          4416: @samp{?} or @samp{!}; a character set matching close-brackets,
        !          4417: quotes or parentheses, repeated any number of times; an alternative in
        !          4418: backslash-parentheses that matches end-of-line, a tab or two spaces; and a
        !          4419: character set matching whitespace characters, repeated any number of times.
        !          4420: 
        !          4421:   Note that the above example shows how to write this regexp when
        !          4422: entering it as part of an Emacs Lisp program. To enter the same regexp
        !          4423: in an interactive command such as @code{re-search-forward} you must
        !          4424: spell it differently:
        !          4425: 
        !          4426: @example
        !          4427: [.?!][]"')]*\($\|^Q^I\| \)[ ^Q^I^Q^J]*
        !          4428: @end example
        !          4429: 
        !          4430: @node Search Case, Replace, Regexps, Search
        !          4431: @section Searching and Case
        !          4432: 
        !          4433: @vindex case-fold-search
        !          4434:   All sorts of searches in Emacs normally ignore the case of the text they
        !          4435: are searching through; if you specify searching for @samp{FOO}, then
        !          4436: @samp{Foo} and @samp{foo} are also considered a match.  Regexps, and in
        !          4437: particular character sets, are included: @samp{[aB]} would match @samp{a}
        !          4438: or @samp{A} or @samp{b} or @samp{B}.@refill
        !          4439: 
        !          4440:   If you do not want this feature, set the variable @code{case-fold-search}
        !          4441: to @code{nil}.  Then all letters must match exactly, including case.  This
        !          4442: is a per-buffer variable; altering the variable affects only the current
        !          4443: buffer, but there is a default value which you can change as well.
        !          4444: @xref{Locals}.
        !          4445: 
        !          4446: @node Replace, Other Repeating Search, Search Case, Search
        !          4447: @section Replacement Commands
        !          4448: @cindex replacement
        !          4449: @cindex string substitution
        !          4450: @cindex global substitution
        !          4451: 
        !          4452:   Global search-and-replace operations are not needed as often in Emacs as
        !          4453: they are in other editors, but they are available.  In addition to the
        !          4454: simple @code{replace-string} command which is like that found in most
        !          4455: editors, there is a @code{query-replace} command which asks you, for each
        !          4456: occurrence of the pattern, whether to replace it.
        !          4457: 
        !          4458:   The replace commands all replace one string (or regexp) with one
        !          4459: replacement string.  It is possible to perform several replacements in
        !          4460: parallel using the command @code{expand-region-abbrevs}.  @xref{Expanding
        !          4461: Abbrevs}.
        !          4462: 
        !          4463: @menu
        !          4464: * Unconditional Replace::  Replacing all matches for a string.
        !          4465: * Regexp Replace::         Replacing all matches for a regexp.
        !          4466: * Replacement and Case::   How replacements preserve case of letters.
        !          4467: * Query Replace::          How to use querying.
        !          4468: @end menu
        !          4469: 
        !          4470: @node Unconditional Replace, Regexp Replace, Replace, Replace
        !          4471: @subsection Unconditional Replacement
        !          4472: @findex replace-string
        !          4473: @findex replace-regexp
        !          4474: 
        !          4475: @table @kbd
        !          4476: @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
        !          4477: Replace every occurrence of @var{string} with @var{newstring}.
        !          4478: @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
        !          4479: Replace every match for @var{regexp} with @var{newstring}.
        !          4480: @end table
        !          4481: 
        !          4482:   To replace every instance of @samp{foo} after point with @samp{bar}, use
        !          4483: the command @kbd{M-x replace-string} with the two arguments @samp{foo} and
        !          4484: @samp{bar}.  Replacement occurs only after point, so if you want to cover
        !          4485: the whole buffer you must go to the beginning first.  All occurrences up to
        !          4486: the end of the buffer are replaced; to limit replacement to part of the
        !          4487: buffer, narrow to that part of the buffer before doing the replacement
        !          4488: (@pxref{Narrowing}).
        !          4489: 
        !          4490:   When @code{replace-string} exits, point is left at the last occurrence
        !          4491: replaced.  The value of point when the @code{replace-string} command was
        !          4492: issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back
        !          4493: there.
        !          4494: 
        !          4495:   A numeric argument restricts replacement to matches that are surrounded
        !          4496: by word boundaries.
        !          4497: 
        !          4498: @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
        !          4499: @subsection Regexp Replacement
        !          4500: 
        !          4501:   @code{replace-string} replaces exact matches for a single string.  The
        !          4502: similar command @code{replace-regexp} replaces any match for a specified
        !          4503: pattern.
        !          4504: 
        !          4505:   In @code{replace-regexp}, the @var{newstring} need not be constant.  It
        !          4506: can refer to all or part of what is matched by the @var{regexp}.  @samp{\&}
        !          4507: in @var{newstring} stands for the entire text being replaced.
        !          4508: @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
        !          4509: whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
        !          4510: For example,@refill
        !          4511: 
        !          4512: @example
        !          4513: M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
        !          4514: @end example
        !          4515: 
        !          4516: @noindent
        !          4517: would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
        !          4518: with @samp{cddr-safe}.
        !          4519: 
        !          4520: @example
        !          4521: M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
        !          4522: @end example
        !          4523: 
        !          4524: @noindent
        !          4525: would perform exactly the opposite replacements.  To include a @samp{\}
        !          4526: in the text to replace with, you must give @samp{\\}.
        !          4527: 
        !          4528: @node Replacement and Case, Query Replace, Regexp Replace, Replace
        !          4529: @subsection Replace Commands and Case
        !          4530: 
        !          4531: @vindex case-replace
        !          4532: @vindex case-fold-search
        !          4533:   If the arguments to a replace command are in lower case, it preserves
        !          4534: case when it makes a replacement.  Thus, the command
        !          4535: 
        !          4536: @example
        !          4537: M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
        !          4538: @end example
        !          4539: 
        !          4540: @noindent
        !          4541: replaces a lower case @samp{foo} with a lower case @samp{bar}, @samp{FOO}
        !          4542: with @samp{BAR}, and @samp{Foo} with @samp{Bar}.  If upper case letters are
        !          4543: used in the second argument, they remain upper case every time that
        !          4544: argument is inserted.  If upper case letters are used in the first
        !          4545: argument, the second argument is always substituted exactly as given, with
        !          4546: no case conversion.  Likewise, if the variable @code{case-replace} is set
        !          4547: to @code{nil}, replacement is done without case conversion.  If
        !          4548: @code{case-fold-search} is set to @code{nil}, case is significant in
        !          4549: matching occurrences of @samp{foo} to replace; also, case conversion of the
        !          4550: replacement string is not done.
        !          4551: 
        !          4552: @node Query Replace,, Replacement and Case, Replace
        !          4553: @subsection Query Replace
        !          4554: @cindex query replace
        !          4555: 
        !          4556: @table @kbd
        !          4557: @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
        !          4558: @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
        !          4559: Replace some occurrences of @var{string} with @var{newstring}.
        !          4560: @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
        !          4561: Replace some matches for @var{regexp} with @var{newstring}.
        !          4562: @end table
        !          4563: 
        !          4564: @kindex M-%
        !          4565: @findex query-replace
        !          4566:   If you want to change only some of the occurrences of @samp{foo} to
        !          4567: @samp{bar}, not all of them, then you cannot use an ordinary
        !          4568: @code{replace-string}.  Instead, use @kbd{M-%} (@code{query-replace}).
        !          4569: This command finds occurrences of @samp{foo} one by one, displays each
        !          4570: occurrence and asks you whether to replace it.  A numeric argument to
        !          4571: @code{query-replace} tells it to consider only occurrences that are bounded
        !          4572: by word-delimiter characters.@refill
        !          4573: 
        !          4574: @findex query-replace-regexp
        !          4575:   Aside from querying, @code{query-replace} works just like
        !          4576: @code{replace-string}, and @code{query-replace-regexp} works
        !          4577: just like @code{replace-regexp}.@refill
        !          4578: 
        !          4579:   The things you can type when you are shown an occurrence of @var{string}
        !          4580: or a match for @var{regexp} are:
        !          4581: 
        !          4582: @kindex SPC (query-replace)
        !          4583: @kindex DEL (query-replace)
        !          4584: @kindex , (query-replace)
        !          4585: @kindex ESC (query-replace)
        !          4586: @kindex . (query-replace)
        !          4587: @kindex ! (query-replace)
        !          4588: @kindex ^ (query-replace)
        !          4589: @kindex C-r (query-replace)
        !          4590: @kindex C-w (query-replace)
        !          4591: @kindex C-l (query-replace)
        !          4592: 
        !          4593: @c WideCommands
        !          4594: @table @kbd
        !          4595: @item @key{SPC}
        !          4596: to replace the occurrence with @var{newstring}.  This preserves case, just
        !          4597: like @code{replace-string}, provided @code{case-replace} is non-@code{nil},
        !          4598: as it normally is.@refill
        !          4599: 
        !          4600: @item @key{DEL}
        !          4601: to skip to the next occurrence without replacing this one.
        !          4602: 
        !          4603: @item , @r{(Comma)}
        !          4604: to replace this occurrence and display the result.  You are then asked
        !          4605: for another input character, except that since the replacement has
        !          4606: already been made, @key{DEL} and @key{SPC} are equivalent.  You could
        !          4607: type @kbd{C-r} at this point (see below) to alter the replaced text.  You
        !          4608: could also type @kbd{C-x u} to undo the replacement; this exits the
        !          4609: @code{query-replace}, so if you want to do further replacement you must use
        !          4610: @kbd{C-x ESC} to restart (@pxref{Repetition}).
        !          4611: 
        !          4612: @item @key{ESC}
        !          4613: to exit without doing any more replacements.
        !          4614: 
        !          4615: @item .@: @r{(Period)}
        !          4616: to replace this occurrence and then exit.
        !          4617: 
        !          4618: @item !
        !          4619: to replace all remaining occurrences without asking again.
        !          4620: 
        !          4621: @item ^
        !          4622: to go back to the location of the previous occurrence (or what used to
        !          4623: be an occurrence), in case you changed it by mistake.  This works by
        !          4624: popping the mark ring.  Only one @kbd{^} in a row is allowed, because
        !          4625: only one previous replacement location is kept during @code{query-replace}.
        !          4626: 
        !          4627: @item C-r
        !          4628: to enter a recursive editing level, in case the occurrence needs to be
        !          4629: edited rather than just replaced with @var{newstring}.  When you are
        !          4630: done, exit the recursive editing level with @kbd{C-M-c} and the next
        !          4631: occurrence will be displayed.  @xref{Recursive Edit}.
        !          4632: 
        !          4633: @item C-w
        !          4634: to delete the occurrence, and then enter a recursive editing level as
        !          4635: in @kbd{C-r}.  Use the recursive edit to insert text to replace the
        !          4636: deleted occurrence of @var{string}.  When done, exit the recursive
        !          4637: editing level with @kbd{C-M-c} and the next occurrence will be
        !          4638: displayed.
        !          4639: 
        !          4640: @item C-l
        !          4641: to redisplay the screen and then give another answer.
        !          4642: 
        !          4643: @item C-h
        !          4644: to display a message summarizing these options, then give another
        !          4645: answer.
        !          4646: @end table
        !          4647: 
        !          4648:   If you type any other character, the @code{query-replace} is exited, and
        !          4649: the character executed as a command.  To restart the @code{query-replace},
        !          4650: use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it
        !          4651: used the minibuffer to read its arguments.  @xref{Repetition, C-x ESC}.
        !          4652: 
        !          4653:   To replace every occurrence, you can start @code{query-replace} at the
        !          4654: beginning of the buffer and type @kbd{!}, or you can use the
        !          4655: @code{replace-string} command at the beginning of the buffer.  To
        !          4656: replace every occurrence in a part of the buffer, narrow to that part
        !          4657: and then run @code{replace-string} or @code{query-replace} at the
        !          4658: beginning of it.  @xref{Narrowing}.
        !          4659: 
        !          4660: @node Other Repeating Search,, Replace, Search
        !          4661: @section Other Search-and-Loop Commands
        !          4662: 
        !          4663:   Here are some other commands that find matches for a regular expression.
        !          4664: They all operate from point to the end of the buffer.
        !          4665: 
        !          4666: @findex list-matching-lines
        !          4667: @findex occur
        !          4668: @findex count-matches
        !          4669: @findex delete-non-matching-lines
        !          4670: @findex delete-matching-lines
        !          4671: @c grosscommands
        !          4672: @table @kbd
        !          4673: @item M-x occur
        !          4674: Print each line that follows point and contains a match for the
        !          4675: specified regexp.  A numeric argument specifies the number of context
        !          4676: lines to print before and after each matching line; the default is
        !          4677: none.
        !          4678: 
        !          4679: @kindex C-c C-c (Occur mode)
        !          4680: The buffer @samp{*Occur*} containing the output serves as a menu for
        !          4681: finding the occurrences in their original context.  Find an occurrence
        !          4682: as listed in @samp{*Occur*}, position point there and type @kbd{C-c
        !          4683: C-c}; this switches to the buffer that was searched and moves point to
        !          4684: the original of the same occurrence.
        !          4685: 
        !          4686: @item M-x list-matching-lines
        !          4687: Synonym for @kbd{M-x occur}.
        !          4688: 
        !          4689: @item M-x count-matches
        !          4690: Print the number of matches following point for the specified regexp.
        !          4691: 
        !          4692: @item M-x delete-non-matching-lines
        !          4693: Delete each line that follows point and does not contain a match for
        !          4694: the specified regexp.
        !          4695: 
        !          4696: @item M-x delete-matching-lines
        !          4697: Delete each line that follows point and contains a match for the
        !          4698: specified regexp.
        !          4699: @end table
        !          4700: 
        !          4701: @node Fixit, Files, Search, Top
        !          4702: @chapter Commands for Fixing Typos
        !          4703: @cindex typos
        !          4704: @cindex mistakes, correcting
        !          4705: 
        !          4706:   In this chapter we describe the commands that are especially useful for
        !          4707: the times when you catch a mistake in your text just after you have made
        !          4708: it, or change your mind while composing text on line.
        !          4709: 
        !          4710: @menu
        !          4711: * Kill Errors:: Commands to kill a batch of recently entered text.
        !          4712: * Transpose::   Exchanging two characters, words, lines, lists...
        !          4713: * Fixing Case:: Correcting case of last word entered.
        !          4714: * Spelling::    Apply spelling checker to a word, or a whole file.
        !          4715: @end menu
        !          4716: 
        !          4717: @node Kill Errors, Transpose, Fixit, Fixit
        !          4718: @section Killing Your Mistakes
        !          4719: 
        !          4720: @table @kbd
        !          4721: @item @key{DEL}
        !          4722: Delete last character (@code{delete-backward-char}).
        !          4723: @item M-@key{DEL}
        !          4724: Kill last word (@code{backward-kill-word}).
        !          4725: @item C-x @key{DEL}
        !          4726: Kill to beginning of sentence (@code{backward-kill-sentence}).
        !          4727: @end table
        !          4728: 
        !          4729: @kindex DEL
        !          4730: @findex delete-backward-char
        !          4731:   The @key{DEL} character (@code{delete-backward-char}) is the most
        !          4732: important correction command.  When used among graphic (self-inserting)
        !          4733: characters, it can be thought of as canceling the last character typed.
        !          4734: 
        !          4735: @kindex M-DEL
        !          4736: @kindex C-x DEL
        !          4737: @findex backward-kill-word
        !          4738: @findex backward-kill-sentence
        !          4739:   When your mistake is longer than a couple of characters, it might be more
        !          4740: convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}.
        !          4741: @kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x
        !          4742: @key{DEL}} kills back to the start of the last sentence.  @kbd{C-x
        !          4743: @key{DEL}} is particularly useful when you are thinking of what to write as
        !          4744: you type it, in case you change your mind about phrasing.
        !          4745: @kbd{M-@key{DEL}} and @kbd{C-x @key{DEL}} save the killed text for
        !          4746: @kbd{C-y} and @kbd{M-y} to retrieve.  @xref{Yanking}.@refill
        !          4747: 
        !          4748:   @kbd{M-@key{DEL}} is often useful even when you have typed only a few
        !          4749: characters wrong, if you know you are confused in your typing and aren't
        !          4750: sure exactly what you typed.  At such a time, you cannot correct with
        !          4751: @key{DEL} except by looking at the screen to see what you did.  It requires
        !          4752: less thought to kill the whole word and start over again.
        !          4753: 
        !          4754: @node Transpose, Fixing Case, Kill Errors, Fixit
        !          4755: @section Transposing Text
        !          4756: 
        !          4757: @table @kbd
        !          4758: @item C-t
        !          4759: Transpose two characters (@code{transpose-chars}).
        !          4760: @item M-t
        !          4761: Transpose two words (@code{transpose-words}).
        !          4762: @item C-M-t
        !          4763: Transpose two balanced expressions (@code{transpose-sexps}).
        !          4764: @item C-x C-t
        !          4765: Transpose two lines (@code{transpose-lines}).
        !          4766: @end table
        !          4767: 
        !          4768: @cindex transposition
        !          4769: @kindex C-t
        !          4770: @findex transpose-chars
        !          4771:   The common error of transposing two characters can be fixed, when they
        !          4772: are adjacent, with the @kbd{C-t} command (@code{transpose-chars}).  Normally,
        !          4773: @kbd{C-t} transposes the two characters on either side of point.  When
        !          4774: given at the end of a line, rather than transposing the last character of
        !          4775: the line with the newline, which would be useless, @kbd{C-t} transposes the
        !          4776: last two characters on the line.  So, if you catch your transposition error
        !          4777: right away, you can fix it with just a @kbd{C-t}.  If you don't catch it so
        !          4778: fast, you must move the cursor back to between the two transposed
        !          4779: characters.  If you transposed a space with the last character of the word
        !          4780: before it, the word motion commands are a good way of getting there.
        !          4781: Otherwise, a reverse search (@kbd{C-r}) is often the best way.
        !          4782: @xref{Search}.
        !          4783: 
        !          4784: 
        !          4785: @kindex C-x C-t
        !          4786: @findex transpose-lines
        !          4787: @kindex M-t
        !          4788: @findex transpose-words
        !          4789: @kindex C-M-t
        !          4790: @findex transpose-sexps
        !          4791:   @kbd{Meta-t} (@code{transpose-words}) transposes the word before point
        !          4792: with the word after point.  It moves point forward over a word, dragging
        !          4793: the word preceding or containing point forward as well.  The punctuation
        !          4794: characters between the words do not move.  For example, @w{@samp{FOO, BAR}}
        !          4795: transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.
        !          4796: 
        !          4797:   @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing
        !          4798: two expressions (@pxref{Lists}), and @kbd{C-x C-t} (@code{transpose-lines})
        !          4799: exchanges lines.  They work like @kbd{M-t} except in determining the
        !          4800: division of the text into syntactic units.
        !          4801: 
        !          4802:   A numeric argument to a transpose command serves as a repeat count: it
        !          4803: tells the transpose command to move the character (word, sexp, line) before
        !          4804: or containing point across several other characters (words, sexps, lines).
        !          4805: For example, @kbd{C-u 3 C-t} moves the character before point forward
        !          4806: across three other characters.  This is equivalent to repeating @kbd{C-t}
        !          4807: three times.  @kbd{C-u - 4 M-t} moves the word before point backward across
        !          4808: four words.  @kbd{C-u - C-M-t} would cancel the effect of plain
        !          4809: @kbd{C-M-t}.@refill
        !          4810: 
        !          4811:   A numeric argument of zero is assigned a special meaning (because
        !          4812: otherwise a command with a repeat count of zero would do nothing): to
        !          4813: transpose the character (word, sexp, line) ending after point with the
        !          4814: one ending after the mark.
        !          4815: 
        !          4816: @node Fixing Case, Spelling, Transpose, Fixit
        !          4817: @section Case Conversion
        !          4818: 
        !          4819: @table @kbd
        !          4820: @item M-- M-l
        !          4821: Convert last word to lower case.  Note @kbd{Meta--} is Meta-minus.
        !          4822: @item M-- M-u
        !          4823: Convert last word to all upper case.
        !          4824: @item M-- M-c
        !          4825: Convert last word to lower case with capital initial.
        !          4826: @end table
        !          4827: 
        !          4828: @findex downcase-word
        !          4829: @findex upcase-word
        !          4830: @findex capitalize-word
        !          4831: @kindex M-@t{-} M-l
        !          4832: @kindex M-@t{-} M-u
        !          4833: @kindex M-@t{-} M-c
        !          4834: @cindex case conversion
        !          4835: @cindex words
        !          4836:   A very common error is to type words in the wrong case.  Because of this,
        !          4837: the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a
        !          4838: special feature when used with a negative argument: they do not move the
        !          4839: cursor.  As soon as you see you have mistyped the last word, you can simply
        !          4840: case-convert it and go on typing.  @xref{Case}.@refill
        !          4841: 
        !          4842: @node Spelling,, Fixing Case, Fixit
        !          4843: @section Checking and Correcting Spelling
        !          4844: @cindex spelling
        !          4845: 
        !          4846: @c doublewidecommands
        !          4847: @table @kbd
        !          4848: @item M-$
        !          4849: Check and correct spelling of word (@code{spell-word}).
        !          4850: @item M-x spell-buffer
        !          4851: Check and correct spelling of each word in the buffer.
        !          4852: @item M-x spell-region
        !          4853: Check and correct spelling of each word in the region.
        !          4854: @item M-x spell-string
        !          4855: Check spelling of specified word.
        !          4856: @end table
        !          4857: 
        !          4858: @kindex M-$
        !          4859: @findex spell-word
        !          4860:   To check the spelling of the word before point, and optionally correct it
        !          4861: as well, use the command @kbd{M-$} (@code{spell-word}).  This command runs
        !          4862: an inferior process containing the @code{spell} program to see whether the
        !          4863: word is correct English.  If it is not, it asks you to edit the word (in
        !          4864: the minibuffer) into a corrected spelling, and then does a @code{query-replace}
        !          4865: to substitute the corrected spelling for the old one throughout the buffer.
        !          4866: 
        !          4867:   If you exit the minibuffer without altering the original spelling, it
        !          4868: means you do not want to do anything to that word.  Then the @code{query-replace}
        !          4869: is not done.
        !          4870: 
        !          4871: @findex spell-buffer
        !          4872:   @kbd{M-x spell-buffer} checks each word in the buffer the same way that
        !          4873: @code{spell-word} does, doing a @code{query-replace} if appropriate for
        !          4874: every incorrect word.@refill
        !          4875: 
        !          4876: @findex spell-region
        !          4877:   @kbd{M-x spell-region} is similar but operates only on the region, not
        !          4878: the entire buffer.
        !          4879: 
        !          4880: @findex spell-string
        !          4881:   @kbd{M-x spell-string} reads a string as an argument and checks whether
        !          4882: that is a correctly spelled English word.  It prints in the echo area a
        !          4883: message giving the answer.
        !          4884: 
        !          4885: @node Files, Buffers, Fixit, Top
        !          4886: @chapter File Handling
        !          4887: @cindex files
        !          4888: 
        !          4889:   The basic unit of stored data in Unix is the @dfn{file}.  To edit a file,
        !          4890: you must tell Emacs to examine the file and prepare a buffer containing a
        !          4891: copy of the file's text.  This is called @dfn{visiting} the file.  Editing
        !          4892: commands apply directly to text in the buffer; that is, to the copy inside
        !          4893: Emacs.  Your changes appear in the file itself only when you @dfn{save} the
        !          4894: buffer back into the file.
        !          4895: 
        !          4896:   In addition to visiting and saving files, Emacs can delete, copy, rename,
        !          4897: and append to files, and operate on file directories.
        !          4898: 
        !          4899: @menu
        !          4900: * File Names::   How to type and edit file name arguments.
        !          4901: * Visiting::     Visiting a file prepares Emacs to edit the file.
        !          4902: * Saving::       Saving makes your changes permanent.
        !          4903: * Reverting::    Reverting cancels all the changes not saved.
        !          4904: * Auto Save::    Auto Save periodically protects against loss of data.
        !          4905: * ListDir::      Listing the contents of a file directory.
        !          4906: * Dired::        ``Editing'' a directory to delete, rename, etc.
        !          4907:                   the files in it.
        !          4908: * Misc File Ops:: Other things you can do on files.
        !          4909: @end menu
        !          4910: 
        !          4911: @node File Names, Visiting, Files, Files
        !          4912: @section File Names
        !          4913: @cindex file names
        !          4914: 
        !          4915:   Most Emacs commands that operate on a file require you to specify the
        !          4916: file name.  (Saving and reverting are exceptions; the buffer knows which
        !          4917: file name to use for them.)  File names are specified using the minibuffer
        !          4918: (@pxref{Minibuffer}).  @dfn{Completion} is available, to make it easier to
        !          4919: specify long file names.  @xref{Completion}.
        !          4920: 
        !          4921:   There is always a @dfn{default file name} which will be used if you type
        !          4922: just @key{RET}, entering an empty argument.  Normally the default file name
        !          4923: is the name of the file visited in the current buffer; this makes it easy
        !          4924: to operate on that file with any of the Emacs file commands.
        !          4925: 
        !          4926: @vindex default-directory
        !          4927:   Each buffer has a default directory, normally the same as the directory
        !          4928: of the file visited in that buffer.  When Emacs reads a file name, if you
        !          4929: do not specify a directory, the default directory is used.  If you specify
        !          4930: a directory in a relative fashion, with a name that does not start with a
        !          4931: slash, it is interpreted with respect to the default directory.  The
        !          4932: default directory is kept in the variable @code{default-directory}, which
        !          4933: has a separate value in every buffer.
        !          4934: 
        !          4935:   For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
        !          4936: the default directory is @file{/u/rms/gnu/}.  If you type just @samp{foo},
        !          4937: which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
        !          4938: @samp{../.login} would stand for @file{/u/rms/.login}.  @samp{new/foo}
        !          4939: would stand for the filename @file{/u/rms/gnu/new/foo}.
        !          4940: 
        !          4941:   The command @kbd{M-x pwd} prints the current buffer's default directory,
        !          4942: and the command @kbd{M-x cd} sets it (to a value read using the
        !          4943: minibuffer).  A buffer's default directory changes only when the @code{cd}
        !          4944: command is used.  A file-visiting buffer's default directory is initialized
        !          4945: to the directory of the file that is visited there.  If a buffer is made
        !          4946: randomly with @kbd{C-x b}, its default directory is copied from that of the
        !          4947: buffer that was current at the time.
        !          4948: 
        !          4949: @vindex insert-default-directory
        !          4950:   The default directory actually appears in the minibuffer when the
        !          4951: minibuffer becomes active to read a file name.  This serves two purposes:
        !          4952: it shows you what the default is, so that you can type a relative file name
        !          4953: and know with certainty what it will mean, and it allows you to edit the
        !          4954: default to specify a different directory.  This insertion of the default
        !          4955: directory is inhibited if the variable @code{insert-default-directory} is
        !          4956: set to @code{nil}.
        !          4957: 
        !          4958:   Note that it is legitimate to type an absolute file name after you enter
        !          4959: the minibuffer, ignoring the presence of the default directory name as part
        !          4960: of the text.  The final minibuffer contents may look invalid, but that is
        !          4961: not so.  @xref{Minibuffer File}.
        !          4962: 
        !          4963:   @samp{$} in a file name is used to substitute environment variables.  For
        !          4964: example, if you have used the C shell command @samp{setenv FOO
        !          4965: rms/hacks} to set up an environment variable named @samp{FOO}, then
        !          4966: you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an
        !          4967: abbreviation for @file{/u/rms/hacks/test.c}.  (In the Bourne-Again
        !          4968: shell, write @code{export FOO=rms/hacks} to define @code{FOO}.)  The
        !          4969: environment variable name consists of all the alphanumeric characters
        !          4970: after the @samp{$}; alternatively, it may be enclosed in braces after
        !          4971: the @samp{$}.  Note that the @samp{setenv} command affects Emacs only
        !          4972: if done before Emacs is started.
        !          4973: @ignore
        !          4974: In @code{sh}
        !          4975: 
        !          4976: @example
        !          4977: FOO=rms/hacks
        !          4978: export FOO
        !          4979: @end example
        !          4980: @end ignore
        !          4981: 
        !          4982:   To access a file with @samp{$} in its name, type @samp{$$}.  This pair
        !          4983: is converted to a single @samp{$} at the same time as variable substitution
        !          4984: is performed for single @samp{$}.  The Lisp function that performs the
        !          4985: substitution is called @code{substitute-in-file-name}.  The substitution
        !          4986: is performed only on filenames read as such using the minibuffer.
        !          4987: 
        !          4988: @node Visiting, Saving, File Names, Files
        !          4989: @section Visiting Files
        !          4990: @cindex visiting files
        !          4991: 
        !          4992: @c WideCommands
        !          4993: @table @kbd
        !          4994: @item C-x C-f
        !          4995: Visit a file (@code{find-file}).
        !          4996: @item C-x C-v
        !          4997: Visit a different file instead of the one visited last
        !          4998: (@code{find-alternate-file}).
        !          4999: @item C-x 4 C-f
        !          5000: Visit a file, in another window (@code{find-file-other-window}).  Don't
        !          5001: change this window.
        !          5002: @end table
        !          5003: 
        !          5004: @cindex files
        !          5005: @cindex visiting
        !          5006: @cindex saving
        !          5007:   @dfn{Visiting} a file means copying its contents into Emacs where you can
        !          5008: edit them.  Emacs makes a new buffer for each file that you visit.  We say
        !          5009: that the buffer is visiting the file that it was created to hold.  Emacs
        !          5010: constructs the buffer name from the file name by throwing away the
        !          5011: directory, keeping just the name proper.  For example, a file named
        !          5012: @file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}.  If
        !          5013: there is already a buffer with that name, a unique name is constructed by
        !          5014: appending @samp{<2>}, @samp{<3>}, or so on, using the lowest number that
        !          5015: makes a name that is not already in use.
        !          5016: 
        !          5017:   Each window's mode line shows the name of the buffer that is being displayed
        !          5018: in that window, so you can always tell what buffer you are editing.
        !          5019: 
        !          5020:   The changes you make with Emacs are made in the Emacs buffer.  They do
        !          5021: not take effect in the file that you visited, or any place permanent, until
        !          5022: you @dfn{save} the buffer.  Saving the buffer means that Emacs writes the
        !          5023: current contents of the buffer into its visited file.  @xref{Saving}.
        !          5024: 
        !          5025: @cindex modified (buffer)
        !          5026:   If a buffer contains changes that have not been saved, the buffer is said
        !          5027: to be @dfn{modified}.  This is important because it implies that some
        !          5028: changes will be lost if the buffer is not saved.  The mode line displays
        !          5029: two stars near the left margin if the buffer is modified.
        !          5030: 
        !          5031: @kindex C-x C-f
        !          5032: @findex find-file
        !          5033:   To visit a file, use the command @kbd{C-x C-f} (@code{find-file}).  Follow
        !          5034: the command with the name of the file you wish to visit, terminated by a
        !          5035: @key{RET}.
        !          5036: 
        !          5037:   The file name is read using the minibuffer (@pxref{Minibuffer}), with
        !          5038: defaulting and completion in the standard manner (@pxref{File Names}).
        !          5039: While in the minibuffer, you can abort @w{@kbd{C-x C-f}} by typing @kbd{C-g}.
        !          5040: 
        !          5041:   Your confirmation that @kbd{C-x C-f} has completed successfully is the
        !          5042: appearance of new text on the screen and a new buffer name in the mode
        !          5043: line.  If the specified file does not exist and could not be created, or
        !          5044: cannot be read, then an error results.  The error message is printed in the
        !          5045: echo area, and includes the file name which Emacs was trying to visit.
        !          5046: 
        !          5047:   If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
        !          5048: another copy.  It selects the existing buffer containing that file.
        !          5049: However, before doing so, it checks that the file itself has not changed
        !          5050: since you visited or saved it last.  If the file has changed, a warning
        !          5051: message is printed.  @xref{Interlocking,,Simultaneous Editing}.
        !          5052: 
        !          5053: @cindex creating files
        !          5054:   What if you want to create a file?  Just visit it.  Emacs prints
        !          5055: @samp{(New File)} in the echo area, but in other respects behaves as if you
        !          5056: had visited an existing empty file.  If you make any changes and save them,
        !          5057: the file is created.
        !          5058: 
        !          5059: @kindex C-x C-v
        !          5060: @findex find-alternate-file
        !          5061:   If you visit a nonexistent file unintentionally (because you typed the
        !          5062: wrong file name), use the @kbd{C-x C-v} (@code{find-alternate-file})
        !          5063: command to visit the file you wanted.  @kbd{C-x C-v} is similar to @kbd{C-x
        !          5064: C-f}, but it kills the current buffer (after first offering to save it if
        !          5065: it is modified).  @kbd{C-x C-v} is allowed even if the current buffer
        !          5066: is not visiting a file.
        !          5067: 
        !          5068: @vindex find-file-run-dired
        !          5069:   If the file you specify is actually a directory, Dired is called on that
        !          5070: directory (@pxref{Dired}).  This can be inhibited by setting the variable
        !          5071: @code{find-file-run-dired} to @code{nil}; then it is an error to try to
        !          5072: visit a directory.
        !          5073: 
        !          5074: @kindex C-x 4 f
        !          5075: @findex find-file-other-window
        !          5076:   @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
        !          5077: except that the buffer containing the specified file is selected in another
        !          5078: window.  The window that was selected before @kbd{C-x 4 f} continues to
        !          5079: show the same buffer it was already showing.  If this command is used when
        !          5080: only one window is being displayed, that window is split in two, with one
        !          5081: window showing the same before as before, and the other one showing the
        !          5082: newly requested file.  @xref{Windows}.
        !          5083: 
        !          5084: @cindex hooks for files
        !          5085: @vindex find-file-hooks
        !          5086: @vindex find-file-not-found-hooks
        !          5087:   There are two hook variables that allow extensions to modify the
        !          5088: operation of visiting files.  Visiting a file that does not exist runs the
        !          5089: functions in the list @code{find-file-not-found-hooks}; the value of this
        !          5090: variable is expected to be a list of functions, and the functions are
        !          5091: called one by one until one of them returns non-@code{nil}.  Any visiting
        !          5092: of a file, whether extant or not, expects @code{find-file-hooks} to
        !          5093: contain a list of functions and calls them all, one by one.  In both cases
        !          5094: the functions receive no arguments.  Visiting a nonexistent file
        !          5095: runs the @code{find-file-not-found-hooks} first.
        !          5096: 
        !          5097:   You can put a local variable specification at the end of a file which
        !          5098: specifies values for Emacs local variables whenever you visit the file.
        !          5099: @xref{File Variables}.
        !          5100: 
        !          5101: @node Saving, Reverting, Visiting, Files
        !          5102: @section Saving Files
        !          5103: 
        !          5104:   @dfn{Saving} a buffer in Emacs means writing its contents back into the file
        !          5105: that was visited in the buffer.
        !          5106: 
        !          5107: @table @kbd
        !          5108: @item C-x C-s
        !          5109: Save the current buffer in its visited file (@code{save-buffer}).
        !          5110: @item C-x s
        !          5111: Save any or all buffers in their visited files (@code{save-some-buffers}).
        !          5112: @item M-~
        !          5113: @c !!! added @* to prevent overfull hbox
        !          5114: Forget that the current buffer has been changed@*(@code{not-modified}).
        !          5115: @item C-x C-w
        !          5116: Save the current buffer in a specified file, and record that file as
        !          5117: the one visited in the buffer (@code{write-file}).
        !          5118: @item M-x set-visited-file-name
        !          5119: Change file the name under which the current buffer will be saved.
        !          5120: @end table
        !          5121: 
        !          5122: @kindex C-x C-s
        !          5123: @findex save-buffer
        !          5124:   When you wish to save the file and make your changes permanent, type
        !          5125: @kbd{C-x C-s} (@code{save-buffer}).  After saving is finished, @kbd{C-x C-s}
        !          5126: prints a message such as
        !          5127: 
        !          5128: @example
        !          5129: Wrote /u/rms/gnu/gnu.tasks
        !          5130: @end example
        !          5131: 
        !          5132: @noindent
        !          5133: If the selected buffer is not modified (no changes have been made in it
        !          5134: since the buffer was created or last saved), saving is not really done,
        !          5135: because it would have no effect.  Instead, @kbd{C-x C-s} prints a message
        !          5136: in the echo area saying
        !          5137: 
        !          5138: @example
        !          5139: (No changes need to be written)
        !          5140: @end example
        !          5141: 
        !          5142: @kindex C-x s
        !          5143: @findex save-some-buffers
        !          5144:   The command @kbd{C-x s} (@code{save-some-buffers}) can save any or all modified
        !          5145: buffers.  First it asks, for each modified buffer, whether to save it.
        !          5146: These questions should be answered with @kbd{y} or @kbd{n}.  @kbd{C-x C-c},
        !          5147: the key that kills Emacs, invokes @code{save-some-buffers} and therefore
        !          5148: asks the same questions.
        !          5149: 
        !          5150: @kindex M-~
        !          5151: @findex not-modified
        !          5152:   If you have changed a buffer and do not want the changes to be saved, you
        !          5153: should take some action to prevent it.  Otherwise, each time you use
        !          5154: @code{save-some-buffers} you are liable to save it by mistake.  One thing
        !          5155: you can do is type @kbd{M-~} (@code{not-modified}), which clears out the
        !          5156: indication that the buffer is modified.  If you do this, none of the save
        !          5157: commands will believe that the buffer needs to be saved.  (@samp{~} is often
        !          5158: used as a mathematical symbol for `not'; thus @kbd{Meta-~} is `not', metafied.)
        !          5159: You could also use @code{set-visited-file-name} (see below) to mark the
        !          5160: buffer as visiting a different file name, one which is not in use for
        !          5161: anything important.  Alternatively, you can undo all the changes made since
        !          5162: the file was visited or saved, by reading the text from the file again.
        !          5163: This is called @dfn{reverting}.  @xref{Reverting}.  You could also undo all
        !          5164: the changes by repeating the undo command @kbd{C-x u} until you have undone
        !          5165: all the changes; but this only works if you have not made more changes than
        !          5166: the undo mechanism can remember.
        !          5167: 
        !          5168: @findex set-visited-file-name
        !          5169:   @kbd{M-x set-visited-file-name} alters the name of the file that the
        !          5170: current buffer is visiting.  It reads the new file name using the
        !          5171: minibuffer.  It can be used on a buffer that is not visiting a file, too.
        !          5172: The buffer's name is changed to correspond to the file it is now visiting
        !          5173: in the usual fashion (unless the new name is in use already for some other
        !          5174: buffer; in that case, the buffer name is not changed).
        !          5175: @code{set-visited-file-name} does not save the buffer in the newly visited
        !          5176: file; it just alters the records inside Emacs so that, if you save the
        !          5177: buffer, it will be saved in that file.  It also marks the buffer as
        !          5178: ``modified'' so that @kbd{C-x C-s} @i{will} save.
        !          5179: 
        !          5180: @kindex C-x C-w
        !          5181: @findex write-file
        !          5182:   If you wish to mark the buffer as visiting a different file and save it
        !          5183: right away, use @kbd{C-x C-w} (@code{write-file}).  It is precisely
        !          5184: equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
        !          5185: @kbd{C-x C-s} used on a buffer that is not visiting with a file has the
        !          5186: same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
        !          5187: buffer as visiting that file, and saves it there.  The default file name in
        !          5188: a buffer that is not visiting a file is made by combining the buffer name
        !          5189: with the buffer's default directory.
        !          5190: 
        !          5191:   If Emacs is about to save a file and sees that the date of the latest
        !          5192: version on disk does not match what Emacs last read or wrote, Emacs
        !          5193: notifies you of this fact, because it probably indicates a problem caused
        !          5194: by simultaneous editing and requires your immediate attention.
        !          5195: @xref{Interlocking,, Simultaneous Editing}.
        !          5196: 
        !          5197: @vindex require-final-newline
        !          5198:   If the variable @code{require-final-newline} is non-@code{nil}, Emacs
        !          5199: puts a newline at the end of any file that doesn't already end in one,
        !          5200: every time a file is saved or written.
        !          5201: 
        !          5202: @vindex write-file-hooks
        !          5203:   You can implement other ways to write files, and other things to be done
        !          5204: before writing them, using the hook variable @code{write-file-hooks}.  The
        !          5205: value of this variable should be a list of Lisp functions.  When a file is
        !          5206: to be written, the functions in the list are called, one by one, with no
        !          5207: arguments.  If one of them returns a non-@code{nil} value, Emacs takes this
        !          5208: to mean that the file has been written in some suitable fashion; the rest
        !          5209: of the functions are not called, and normal writing is not done.
        !          5210: 
        !          5211: @menu
        !          5212: * Backup::       How Emacs saves the old version of your file.
        !          5213: * Interlocking:: How Emacs protects against simultaneous editing
        !          5214:                   of one file by two users.
        !          5215: @end menu
        !          5216: 
        !          5217: @node Backup, Interlocking, Saving, Saving
        !          5218: @subsection Backup Files
        !          5219: @cindex backup file
        !          5220: @vindex make-backup-files
        !          5221: 
        !          5222:   Because Unix does not provide version numbers in file names, rewriting a
        !          5223: file in Unix automatically destroys all record of what the file used to
        !          5224: contain.  Thus, saving a file from Emacs throws away the old contents of
        !          5225: the file---or it would, except that Emacs carefully copies the old contents
        !          5226: to another file, called the @dfn{backup} file, before actually saving
        !          5227: (provided the variable @code{make-backup-files} is non-@code{nil};
        !          5228: backup files are not written if this variable is @code{nil}).
        !          5229: 
        !          5230:   At your option, Emacs can keep either a single backup file or a series of
        !          5231: numbered backup files for each file that you edit.
        !          5232: 
        !          5233:   Emacs makes a backup for a file only the first time the file is saved
        !          5234: from one buffer.  No matter how many times you save a file, its backup file
        !          5235: continues to contain the contents from before the file was visited.
        !          5236: Normally this means that the backup file contains the contents from before
        !          5237: the current editing session; however, if you kill the buffer and then visit
        !          5238: the file again, a new backup file will be made by the next save.
        !          5239: 
        !          5240: @menu
        !          5241: * Names: Backup Names.         How backup files are named;
        !          5242:                                Choosing single or numbered backup files.
        !          5243: * Deletion: Backup Deletion.   Emacs deletes excess numbered backups.
        !          5244: * Copying: Backup Copying.     Backups can be made by copying or renaming.
        !          5245: @end menu
        !          5246: 
        !          5247: @node Backup Names, Backup Deletion, Backup, Backup
        !          5248: @subsubsection Single or Numbered Backups
        !          5249: 
        !          5250:   If you choose to have a single backup file (this is the default),
        !          5251: the backup file's name is constructed by appending @samp{~} to the
        !          5252: file name being edited; thus, the backup file for @file{eval.c} would
        !          5253: be @file{eval.c~}.
        !          5254: 
        !          5255:   If you choose to have a series of numbered backup files, backup file
        !          5256: names are made by appending @samp{.~}, the number, and another @samp{~} to
        !          5257: the original file name.  Thus, the backup files of @file{eval.c} would be
        !          5258: called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
        !          5259: like @file{eval.c.~259~} and beyond.
        !          5260: 
        !          5261:   If protection stops you from writing backup files under the usual names,
        !          5262: the backup file is written as @file{%backup%~} in your home directory.
        !          5263: Only one such file can exist, so only the most recently made such backup is
        !          5264: available.
        !          5265: 
        !          5266: @vindex version-control
        !          5267:   The choice of single backup or numbered backups is controlled by the
        !          5268: variable @code{version-control}.  Its possible values are
        !          5269: 
        !          5270: @table @code
        !          5271: @item t
        !          5272: Make numbered backups.
        !          5273: @item nil
        !          5274: Make numbered backups for files that have numbered backups already.
        !          5275: Otherwise, make single backups.
        !          5276: @item never
        !          5277: Do not in any case make numbered backups; always make single backups.
        !          5278: @end table
        !          5279: 
        !          5280: @noindent
        !          5281: @code{version-control} may be set locally in an individual buffer to
        !          5282: control the making of backups for that buffer's file.  For example,
        !          5283: Rmail mode locally sets @code{version-control} to @code{never} to make sure
        !          5284: that there is only one backup for an Rmail file.  @xref{Locals}.
        !          5285: 
        !          5286: @node Backup Deletion, Backup Copying, Backup Names, Backup
        !          5287: @subsubsection Automatic Deletion of Backups
        !          5288: 
        !          5289: @cindex backups, automatic deleting of
        !          5290: @cindex versions, keeping old
        !          5291: @vindex kept-old-versions
        !          5292: @vindex kept-new-versions
        !          5293:   To prevent unlimited consumption of disk space, Emacs can delete numbered
        !          5294: backup versions automatically.  Generally Emacs keeps the first few backups
        !          5295: and the latest few backups, deleting any in between.  This happens every
        !          5296: time a new backup is made.  The two variables that control the deletion are
        !          5297: @code{kept-old-versions} and @code{kept-new-versions}.  Their values are, respectively
        !          5298: the number of oldest (lowest-numbered) backups to keep and the number of
        !          5299: newest (highest-numbered) ones to keep, each time a new backup is made.
        !          5300: Recall that these values are used just after a new backup version is made;
        !          5301: that newly made backup is included in the count in @code{kept-new-versions}.
        !          5302: By default, both variables are 2.
        !          5303: 
        !          5304: @vindex trim-versions-without-asking
        !          5305:   If @code{trim-versions-without-asking} is non-@code{nil}, the excess
        !          5306: middle versions are deleted without a murmur.  If it is @code{nil}, the
        !          5307: default, then you are asked whether the excess middle versions should
        !          5308: really be deleted.
        !          5309: 
        !          5310:   Dired's @kbd{.} (Period) command can also be used to delete old versions.
        !          5311: @xref{Dired}.
        !          5312: 
        !          5313: @node Backup Copying,, Backup Deletion, Backup
        !          5314: @subsubsection Copying vs. Renaming
        !          5315: @c !!!! zzzz change back after fixref
        !          5316: @c subsubsection Copying vs.@: Renaming
        !          5317: 
        !          5318:   Backup files can be made by copying the old file or by renaming it.  This
        !          5319: makes a difference when the old file has multiple names.  If the old file
        !          5320: is renamed into the backup file, then the alternate names become names for
        !          5321: the backup file.  If the old file is copied instead, then the alternate
        !          5322: names remain names for the file that you are editing, and the contents
        !          5323: accessed by those names will be the new contents.
        !          5324: 
        !          5325:   The method of making a backup file may also affect the file's owner
        !          5326: and group.  If copying is used, these do not change.  If renaming is used,
        !          5327: you become the file's owner, and the file's group becomes the default
        !          5328: (different operating systems have different defaults for the group).
        !          5329: 
        !          5330:   Having the owner change is usually a good idea, because then the owner
        !          5331: always shows who last edited the file.  Also, the owners of the backups
        !          5332: show who produced those versions.  Occasionally there is a file whose
        !          5333: owner should not change; it is a good idea for such files to contain
        !          5334: local variable lists to set @code{backup-by-copying-when-mismatch} for
        !          5335: them alone (@pxref{File Variables}).
        !          5336: 
        !          5337: @vindex backup-by-copying
        !          5338: @vindex backup-by-copying-when-linked
        !          5339: @vindex backup-by-copying-when-mismatch
        !          5340:   The choice of renaming or copying is controlled by three variables.
        !          5341: Normally, renaming is done.  If the variable @code{backup-by-copying} is
        !          5342: non-@code{nil}, copying is used.  Otherwise, if the variable
        !          5343: @code{backup-by-copying-when-linked} is non-@code{nil}, then copying is
        !          5344: done for files that have multiple names, but renaming may still done when
        !          5345: the file being edited has only one name.  If the variable
        !          5346: @code{backup-by-copying-when-mismatch} is non-@code{nil}, then copying is
        !          5347: done if renaming would cause the file's owner or group to change.  @refill
        !          5348: 
        !          5349: @node Interlocking,,Backup,Saving
        !          5350: @subsection Protection against Simultaneous Editing
        !          5351: 
        !          5352: @cindex buffer locking
        !          5353: @cindex locking buffers
        !          5354: @cindex interlocking buffers
        !          5355: @cindex file dates
        !          5356: @cindex simultaneous editing
        !          5357:   Simultaneous editing occurs when two users visit the same file, both make
        !          5358: changes, and then both save them.  If nobody were informed that this was
        !          5359: happening, whichever user saved first would later find that his changes
        !          5360: were lost.  On some systems, Emacs notices immediately when the second user
        !          5361: starts to change the file, and issues an immediate warning.  When this is
        !          5362: not possible, or if the second user has gone on to change the file despite
        !          5363: the warning, Emacs checks later when the file is saved, and issues a second
        !          5364: warning when a user is about to overwrite a file containing another user's
        !          5365: changes.  If the editing user takes the proper corrective action at this
        !          5366: point, he can prevent actual loss of work.
        !          5367: 
        !          5368: @findex ask-user-about-lock
        !          5369:   When you make the first modification in an Emacs buffer that is visiting
        !          5370: a file, Emacs records that you have locked the file.  (It does this by
        !          5371: writing another file in a directory reserved for this purpose.)  The lock
        !          5372: is removed when you save the changes.  The idea is that the file is locked
        !          5373: whenever the buffer is modified.  If you begin to modify the buffer while
        !          5374: the visited file is locked by someone else, this constitutes a collision,
        !          5375: and Emacs asks you what to do.  It does this by calling the Lisp function
        !          5376: @code{ask-user-about-lock}, which you can redefine for the sake of
        !          5377: customization.  The standard definition of this function asks you a
        !          5378: question and accepts three possible answers:
        !          5379: 
        !          5380: @table @kbd
        !          5381: @item s
        !          5382: Steal the lock.  Whoever was already changing the file loses the lock,
        !          5383: and you gain the lock.
        !          5384: @item p
        !          5385: Proceed.  Go ahead and edit the file despite its being locked by someone else.
        !          5386: @item q
        !          5387: Quit.  This causes an error (@code{file-locked}) and the modification you
        !          5388: were trying to make in the buffer does not actually take place.
        !          5389: @end table
        !          5390: 
        !          5391:   Note that locking works on the basis of a file name; if a file has
        !          5392: multiple names, Emacs does not realize that the two names are the same file
        !          5393: and cannot prevent two user from editing it simultaneously under different
        !          5394: names.  However, basing locking on names means that Emacs can interlock the
        !          5395: editing of new files that will not really exist until they are saved.
        !          5396: 
        !          5397:   Some systems are not configured to allow Emacs to make locks.  On
        !          5398: these systems, Emacs cannot detect trouble in advance, but it still can
        !          5399: detect it in time to prevent you from overwriting someone else's changes.
        !          5400: 
        !          5401:   Every time Emacs saves a buffer, it first checks the last-modification
        !          5402: date of the existing file on disk to see that it has not changed since the
        !          5403: file was last visited or saved.  If the date does not match, it implies
        !          5404: that changes were made in the file in some other way, and these changes are
        !          5405: about to be lost if Emacs actually does save.  To prevent this, Emacs
        !          5406: prints a warning message and asks for confirmation before saving.
        !          5407: Occasionally you will know why the file was changed and know that it does
        !          5408: not matter; then you can answer @kbd{yes} and proceed.  Otherwise, you should
        !          5409: cancel the save with @kbd{C-g} and investigate the situation.
        !          5410: 
        !          5411:   The first thing you should do when notified that simultaneous editing has
        !          5412: already taken place is to list the directory with @kbd{C-u C-x C-d}
        !          5413: (@pxref{ListDir,,Directory Listing}).  This will show the file's
        !          5414: current author.  You should attempt to contact that person to warn him
        !          5415: or her not to continue editing.  Often the next step is to save the
        !          5416: contents of your Emacs buffer under a different name, and use
        !          5417: @code{diff} to compare the two files.@refill
        !          5418: 
        !          5419:   Simultaneous editing checks are also made when you visit with @kbd{C-x
        !          5420: C-f} a file that is already visited and when you start to modify a file.
        !          5421: This is not strictly necessary, but it can cause you to find out about the
        !          5422: problem earlier, when perhaps correction takes less work.
        !          5423: 
        !          5424: @node Reverting, Auto Save, Saving, Files
        !          5425: @section Reverting a Buffer
        !          5426: @findex revert-buffer
        !          5427: @cindex drastic changes
        !          5428: 
        !          5429:   If you have made extensive changes to a file and then change your mind
        !          5430: about them, you can get rid of them by reading in the previous version of
        !          5431: the file.  To do this, use @kbd{M-x revert-buffer}, which operates on the
        !          5432: current buffer.  Since this is a very dangerous thing to do, you must
        !          5433: confirm it with @kbd{yes}.
        !          5434: 
        !          5435:   If the current buffer has been auto-saved more recently than it has been
        !          5436: saved for real, @code{revert-buffer} offers to read the auto save file
        !          5437: instead of the visited file (@pxref{Auto Save}).  This question comes
        !          5438: before the usual request for confirmation, and demands @kbd{y} or @kbd{n}
        !          5439: as an answer.  If you have started to type @kbd{yes} for confirmation
        !          5440: without realizing that the other question was going to be asked, the
        !          5441: @kbd{y} will answer that question, but the @kbd{es} will not be valid
        !          5442: confirmation.  So you will have a chance to cancel the operation with
        !          5443: @kbd{C-g} and try it again with the answers that you really intend.
        !          5444: 
        !          5445:   @code{revert-buffer} keeps point at the same distance (measured in
        !          5446: characters) from the beginning of the file.  If the file was edited only
        !          5447: slightly, you will be at approximately the same piece of text after
        !          5448: reverting as before.  If you have made drastic changes, the same value of
        !          5449: point in the old file may address a totally different piece of text.
        !          5450: 
        !          5451:   A buffer reverted from its visited file is marked ``not modified'' until
        !          5452: another change is made.
        !          5453: 
        !          5454:   Some kinds of buffers whose contents reflect data bases other than files,
        !          5455: such as Dired buffers, can also be reverted.  For them, reverting means
        !          5456: recalculating their contents from the appropriate data base.  Buffers
        !          5457: created randomly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
        !          5458: reports an error when asked to do so.
        !          5459: 
        !          5460: @node Auto Save, ListDir, Reverting, Files
        !          5461: @section Auto-Saving: Protection Against Disasters
        !          5462: @cindex Auto-Save mode
        !          5463: @cindex crashes
        !          5464: 
        !          5465:   Emacs saves all the visited files from time to time (based on counting
        !          5466: your keystrokes) without being asked.  This is called @dfn{auto-saving}.
        !          5467: It prevents you from losing more than a limited amount of work if the
        !          5468: system crashes.
        !          5469: 
        !          5470:   When Emacs determines that it is time for auto-saving, each buffer is
        !          5471: considered, and is auto-saved if auto-saving is turned on for it and it has
        !          5472: been changed since the last time it was auto-saved.  If any auto-saving is
        !          5473: done, the message @samp{Auto-saving...} is displayed in the echo area until
        !          5474: auto-saving is finished.  Errors occurring during auto-saving are caught
        !          5475: so that they do not interfere with the execution of commands you have been
        !          5476: typing.
        !          5477: 
        !          5478: @menu
        !          5479: * Files: Auto Save Files.
        !          5480: * Control: Auto Save Control.
        !          5481: * Recover::            Recovering text from auto-save files.
        !          5482: @end menu
        !          5483: 
        !          5484: @node Auto Save Files, Auto Save Control, Auto Save, Auto Save
        !          5485: @subsection Auto-Save Files
        !          5486: 
        !          5487:   Auto-saving does not normally save in the files that you visited, because
        !          5488: it can be very undesirable to save a program that is in an inconsistent
        !          5489: state when you have made half of a planned change.  Instead, auto-saving
        !          5490: is done in a different file called the @dfn{auto-save file}, and the
        !          5491: visited file is changed only when you request saving explicitly (such as
        !          5492: with @kbd{C-x C-s}).
        !          5493: 
        !          5494:   Normally, the auto-save file name is made by appending @samp{#} to the
        !          5495: front and rear of the visited file name.  Thus, a buffer visiting file
        !          5496: @file{foo.c} would be auto-saved in a file @file{#foo.c#}.  Most buffers
        !          5497: that are not visiting files are auto-saved only if you request it
        !          5498: explicitly; when they are auto-saved, the auto-save file name is made by
        !          5499: appending @samp{#%} to the front and @samp{#} to the rear of buffer name.
        !          5500: For example, the @samp{*mail*} buffer in which you compose messages to be
        !          5501: sent is auto-saved in a file named @file{#%*mail*#}.  Auto-save file names
        !          5502: are made this way unless you reprogram parts of Emacs to do something
        !          5503: different (the functions @code{make-auto-save-file-name} and
        !          5504: @code{auto-save-file-name-p}).  The file name to be used for auto-saving
        !          5505: in a buffer is calculated when auto-saving is turned on in that buffer.
        !          5506: 
        !          5507: @vindex auto-save-visited-file-name
        !          5508:   If you want auto-saving to be done in the visited file, set the variable
        !          5509: @code{auto-save-visited-file-name} to be non-@code{nil}.  In this mode,
        !          5510: there is really no difference between auto-saving and explicit saving.
        !          5511: 
        !          5512: @vindex delete-auto-save-files
        !          5513:   A buffer's auto-save file is deleted when you save the buffer in its
        !          5514: visited file.  To inhibit this, set the variable @code{delete-auto-save-files}
        !          5515: to @code{nil}.  Changing the visited file name with @kbd{C-x C-w} or
        !          5516: @code{set-visited-file-name} renames any auto-save file to go with
        !          5517: the new visited name.
        !          5518: 
        !          5519: @node Auto Save Control, Recover, Auto Save Files, Auto Save
        !          5520: @subsection Controlling Auto-Saving
        !          5521: 
        !          5522: @vindex auto-save-default
        !          5523: @findex auto-save-mode
        !          5524:   Each time you visit a file, auto-saving is turned on for that file's
        !          5525: buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
        !          5526: in batch mode; @pxref{Entering Emacs}).  The default for this variable is
        !          5527: @code{t}, so auto-saving is the usual practice for file-visiting buffers.
        !          5528: Auto-saving can be turned on or off for any existing buffer with the
        !          5529: command @kbd{M-x auto-save-mode}.  Like other minor mode commands, @kbd{M-x
        !          5530: auto-save-mode} turns auto-saving on with a positive argument, off with a
        !          5531: zero or negative argument; with no argument, it toggles.
        !          5532: 
        !          5533: @vindex auto-save-interval
        !          5534: @findex do-auto-save
        !          5535:   Emacs does auto-saving periodically based on counting how many characters
        !          5536: you have typed since the last time auto-saving was done.  The variable
        !          5537: @code{auto-save-interval} specifies how many characters there are between
        !          5538: auto-saves.  By default, it is 300.  Emacs also auto-saves whenever you
        !          5539: call the function @code{do-auto-save}.
        !          5540: 
        !          5541:   Emacs also does auto-saving whenever it gets a fatal error.  This
        !          5542: includes killing the Emacs job with a shell command such as @code{kill
        !          5543: %emacs}, or disconnecting a phone line or network connection.
        !          5544: 
        !          5545: @node Recover,, Auto Save Control, Auto Save
        !          5546: @subsection Recovering Data from Auto-Saves
        !          5547: 
        !          5548: @findex recover-file
        !          5549:   The way to use the contents of an auto-save file to recover from a loss
        !          5550: of data is with the command @kbd{M-x recover-file @key{RET} @var{file}
        !          5551: @key{RET}}.  This visits @var{file} and then (after your confirmation)
        !          5552: restores the contents from its auto-save file @file{#@var{file}#}.  You
        !          5553: can then save with @kbd{C-x C-s} to put the recovered text into @var{file}
        !          5554: itself.  For example, to recover file @file{foo.c} from its auto-save file
        !          5555: @file{#foo.c#}, do:@refill
        !          5556: 
        !          5557: @example
        !          5558: M-x recover-file @key{RET} foo.c @key{RET}
        !          5559: C-x C-s
        !          5560: @end example
        !          5561: 
        !          5562:   Before asking for confirmation, @kbd{M-x recover-file} displays a
        !          5563: directory listing describing the specified file and the auto-save file,
        !          5564: so you can compare their sizes and dates.  If the auto-save file
        !          5565: is older, @kbd{M-x recover-file} does not offer to read it.
        !          5566: 
        !          5567:   Auto-saving is disabled by @kbd{M-x recover-file} because using
        !          5568: this command implies that the auto-save file contains valuable data
        !          5569: from a past session.  If you save the data in the visited file and
        !          5570: then go on to make new changes, you should turn auto-saving back on
        !          5571: with @kbd{M-x auto-save-mode}.
        !          5572: 
        !          5573: @node ListDir, Dired, Auto Save, Files
        !          5574: @section Listing a File Directory
        !          5575: 
        !          5576: @cindex file directory
        !          5577: @cindex directory listing
        !          5578: @cindex listing a directory
        !          5579:   Files are classified by Unix into @dfn{directories}.  A @dfn{directory
        !          5580: listing} is a list of all the files in a directory.  Emacs provides
        !          5581: directory listings in brief format (file names only) and verbose format
        !          5582: (sizes, dates, and authors included).
        !          5583: 
        !          5584: @table @kbd
        !          5585: @item C-x C-d @var{dir-or-pattern}
        !          5586: Print a brief directory listing (@code{list-directory}).
        !          5587: @item C-u C-x C-d @var{dir-or-pattern}
        !          5588: Print a verbose directory listing.
        !          5589: @end table
        !          5590: 
        !          5591: @findex list-directory
        !          5592: @kindex C-x C-d
        !          5593:   The command to print a directory listing is @kbd{C-x C-d} (@code{list-directory}).
        !          5594: It reads using the minibuffer a file name which is either a directory to be
        !          5595: listed or a wildcard-containing pattern for the files to be listed.  For
        !          5596: example,
        !          5597: 
        !          5598: @example
        !          5599: C-x C-d /u2/emacs/etc @key{RET}
        !          5600: @end example
        !          5601: 
        !          5602: @noindent
        !          5603: lists all the files in directory @file{/u2/emacs/etc}.  An example of
        !          5604: specifying a file name pattern is
        !          5605: 
        !          5606: @example
        !          5607: C-x C-d /u2/emacs/src/*.c @key{RET}
        !          5608: @end example
        !          5609: 
        !          5610:   Normally, @kbd{C-x C-d} prints a brief directory listing containing just
        !          5611: file names.  A numeric argument (regardless of value) tells it to print a
        !          5612: verbose listing (like @code{ls -l}).
        !          5613: 
        !          5614: @vindex list-directory-brief-switches
        !          5615: @vindex list-directory-verbose-switches
        !          5616:   The text of a directory listing is obtained by running @code{ls} in an
        !          5617: inferior process.  Two Emacs variables control the switches passed to
        !          5618: @code{ls}: @code{list-directory-brief-switches} is a string giving the
        !          5619: switches to use in brief listings (@code{"-CF"} by default), and
        !          5620: @code{list-directory-verbose-switches} is a string giving the switches to
        !          5621: use in a verbose listing (@code{"-l"} by default).
        !          5622: 
        !          5623: @node Dired, Misc File Ops, ListDir, Files
        !          5624: @section Dired, the Directory Editor
        !          5625: @cindex Dired
        !          5626: @cindex deletion (of files)
        !          5627: 
        !          5628:   Dired makes it easy to delete or visit many of the files in a single
        !          5629: directory at once.  It makes an Emacs buffer containing a listing of the
        !          5630: directory.  You can use the normal Emacs commands to move around in this
        !          5631: buffer, and special Dired commands to operate on the files.
        !          5632: 
        !          5633: @menu
        !          5634: * Enter: Dired Enter.         How to invoke Dired.
        !          5635: * Edit: Dired Edit.           Editing the Dired buffer.
        !          5636: * Deletion: Dired Deletion.   Deleting files with Dired.
        !          5637: * Immed: Dired Immed.         Other file operations through Dired.
        !          5638: @end menu
        !          5639: 
        !          5640: @node Dired Enter, Dired Edit, Dired, Dired
        !          5641: @subsection Entering Dired
        !          5642: 
        !          5643: @findex dired
        !          5644: @kindex C-x d
        !          5645: @cindex Dired mode
        !          5646: @vindex dired-listing-switches
        !          5647:   To invoke dired, do @kbd{C-x d} or @kbd{M-x dired}.  The command reads a
        !          5648: directory name or wildcard file name pattern as a minibuffer argument just
        !          5649: like the @code{list-directory} command, @kbd{C-x C-d}.  Where @code{dired}
        !          5650: differs from @code{list-directory} is in naming the buffer after the
        !          5651: directory name or the wildcard pattern used for the listing, and putting
        !          5652: the buffer into Dired mode so that the special commands of Dired are
        !          5653: available in it.  The variable @code{dired-listing-switches} is a string
        !          5654: used as an argument to @code{ls} in making the directory; this string
        !          5655: @i{must} contain @samp{-l}.
        !          5656: 
        !          5657: @findex dired-other-window
        !          5658: @kindex C-x 4 d
        !          5659:   To display the Dired buffer in another window rather than in the selected
        !          5660: window, use @kbd{C-x 4 d} (@code{dired-other-window)} instead of @kbd{C-x d}.
        !          5661: 
        !          5662: @node Dired Edit, Dired Deletion, Dired Enter, Dired
        !          5663: @subsection Editing in Dired
        !          5664: 
        !          5665:   Once the Dired buffer exists, you can switch freely between it and other
        !          5666: Emacs buffers.  Whenever the Dired buffer is selected, certain special
        !          5667: commands are provided that operate on files that are listed.  The Dired
        !          5668: buffer is ``read-only'', and inserting text in it is not useful, so
        !          5669: ordinary printing characters such as @kbd{d} and @kbd{x} are used for Dired
        !          5670: commands.  Most Dired commands operate on the file described by the line
        !          5671: that point is on.  Some commands perform operations immediately; others
        !          5672: ``flag'' the file to be operated on later.
        !          5673: 
        !          5674:   Most Dired commands that operate on the current line's file also treat a
        !          5675: numeric argument as a repeat count, meaning to act on the files of the
        !          5676: next few lines.  A negative argument means to operate on the files of the
        !          5677: preceding lines, and leave point on the first of those lines.
        !          5678: 
        !          5679:   All the usual Emacs cursor motion commands are available in Dired
        !          5680: buffers.  Some special purpose commands are also provided.  The keys
        !          5681: @kbd{C-n} and @kbd{C-p} are redefined so that they try to position
        !          5682: the cursor at the beginning of the filename on the line, rather than
        !          5683: at the beginning of the line.
        !          5684: 
        !          5685:   For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent to
        !          5686: @kbd{C-n}.  @kbd{p} is equivalent to @kbd{C-p}.  Moving by lines is done so
        !          5687: often in Dired that it deserves to be easy to type.  @key{DEL} (move up and
        !          5688: unflag) is often useful simply for moving up.@refill
        !          5689: 
        !          5690:   The @kbd{g} command in Dired runs @code{revert-buffer} to reinitialize
        !          5691: the buffer from the actual disk directory and show any changes made in the
        !          5692: directory by programs other than Dired.  All deletion flags in the Dired
        !          5693: buffer are lost when this is done.
        !          5694: 
        !          5695: @node Dired Deletion, Dired Immed, Dired Edit, Dired
        !          5696: @subsection Deleting Files with Dired
        !          5697: 
        !          5698:   The primary use of Dired is to flag files for deletion and then delete
        !          5699: them.
        !          5700: 
        !          5701: @table @kbd
        !          5702: @item d
        !          5703: Flag this file for deletion.
        !          5704: @item u
        !          5705: Remove deletion-flag on this line.
        !          5706: @item @key{DEL}
        !          5707: Remove deletion-flag on previous line, moving point to that line.
        !          5708: @item x
        !          5709: Delete the files that are flagged for deletion.
        !          5710: @item #
        !          5711: Flag all auto-save files (files whose names start and end with @samp{#})
        !          5712: for deletion (@pxref{Auto Save}).
        !          5713: @item ~
        !          5714: Flag all backup files (files whose names end with @samp{~}) for deletion
        !          5715: (@pxref{Backup}).
        !          5716: @item .@: @r{(Period)}
        !          5717: Flag excess numeric backup files for deletion.  The oldest and newest
        !          5718: few backup files of any one file are exempt; the middle ones are flagged.
        !          5719: @end table
        !          5720: 
        !          5721:   You can flag a file for deletion by moving to the line describing the
        !          5722: file and typing @kbd{d} or @kbd{C-d}.  The deletion flag is visible as a
        !          5723: @samp{D} at the beginning of the line.  Point is moved to the beginning of
        !          5724: the next line, so that repeated @kbd{d} commands flag successive files.
        !          5725: 
        !          5726:   The files are flagged for deletion rather than deleted immediately to
        !          5727: avoid the danger of deleting a file accidentally.  Until you direct Dired
        !          5728: to delete the flagged files, you can remove deletion flags using the
        !          5729: commands @kbd{u} and @key{DEL}.  @kbd{u} works just like @kbd{d}, but
        !          5730: removes flags rather than making flags.  @key{DEL} moves upward, removing
        !          5731: flags; it is like @kbd{u} with numeric argument automatically negated.
        !          5732: 
        !          5733:   To delete the flagged files, type @kbd{x}.  This command first displays a
        !          5734: list of all the file names flagged for deletion, and requests confirmation
        !          5735: with @kbd{yes}.  Once you confirm, all the flagged files are deleted, and their
        !          5736: lines are deleted from the text of the Dired buffer.  The shortened Dired
        !          5737: buffer remains selected.  If you answer @kbd{no} or quit with @kbd{C-g}, you
        !          5738: return immediately to Dired, with the deletion flags still present and no
        !          5739: files actually deleted.
        !          5740: 
        !          5741:   The @kbd{#}, @kbd{~} and @kbd{.} commands flag many files for
        !          5742: deletion, based on their names.  These commands are useful precisely
        !          5743: because they do not actually delete any files; you can remove the
        !          5744: deletion flags from any flagged files that you really wish to keep.@refill
        !          5745: 
        !          5746:   @kbd{#} flags for deletion all files that appear to have been made by
        !          5747: auto-saving (that is, files whose names begin and end with @samp{#}).
        !          5748: @kbd{~} flags for deletion all files that appear to have been made as
        !          5749: backups for files that were edited (that is, files whose names end with
        !          5750: @samp{~}).
        !          5751: 
        !          5752: @vindex dired-kept-versions
        !          5753:   @kbd{.} (Period) flags just some of the backup files for deletion: only
        !          5754: numeric backups that are not among the oldest few nor the newest few
        !          5755: backups of any one file.  Normally @code{dired-kept-versions} (not
        !          5756: @code{kept-new-versions}; that applies only when saving) specifies the
        !          5757: number of newest versions of each file to keep, and
        !          5758: @code{kept-old-versions} specifies the number of oldest versions to keep.
        !          5759: Period with a positive numeric argument, as in @kbd{C-u 3 .}, specifies the
        !          5760: number of newest versions to keep, overriding @code{dired-kept-versions}.
        !          5761: A negative numeric argument overrides @code{kept-old-versions}, using minus
        !          5762: the value of the argument to specify the number of oldest versions of each
        !          5763: file to keep.@refill
        !          5764: 
        !          5765: @node Dired Immed,, Dired Deletion, Dired
        !          5766: @subsection Immediate File Operations in Dired
        !          5767: 
        !          5768:   Some file operations in Dired take place immediately when they are
        !          5769: requested.
        !          5770: 
        !          5771: @table @kbd
        !          5772: @item c
        !          5773: Copies the file described on the current line.  You must supply a file name
        !          5774: to copy to, using the minibuffer.
        !          5775: @item f
        !          5776: Visits the file described on the current line.  It is just like typing
        !          5777: @kbd{C-x C-f} and supplying that file name.  If the file on this line is a
        !          5778: subdirectory, @kbd{f} actually causes Dired to be invoked on that
        !          5779: subdirectory.  @xref{Visiting}.
        !          5780: @item o
        !          5781: Like @kbd{f}, but uses another window to display the file's buffer.  The
        !          5782: Dired buffer remains visible in the first window.  This is like using
        !          5783: @kbd{C-x 4 C-f} to visit the file.  @xref{Windows}.
        !          5784: @item r
        !          5785: Renames the file described on the current line.  You must supply a file
        !          5786: name to rename to, using the minibuffer.
        !          5787: @item v
        !          5788: Views the file described on this line using @kbd{M-x view-file}.  Viewing a
        !          5789: file is like visiting it, but is slanted toward moving around in the file
        !          5790: conveniently and does not allow changing the file.  @xref{Misc File
        !          5791: Ops,View File}.  Viewing a file that is a directory runs Dired on that
        !          5792: directory.@refill
        !          5793: @end table
        !          5794: 
        !          5795: @node Misc File Ops,, Dired, Files
        !          5796: @section Miscellaneous File Operations
        !          5797: 
        !          5798:   Emacs has commands for performing many other operations on files.
        !          5799: All operate on one file; they do not accept wild card file names.
        !          5800: 
        !          5801: @findex view-file
        !          5802: @cindex viewing
        !          5803:   @kbd{M-x view-file} allows you to scan or read a file by sequential
        !          5804: screenfuls.  It reads a file name argument using the minibuffer.  After
        !          5805: reading the file into an Emacs buffer, @code{view-file} reads and displays
        !          5806: one windowful.  You can then type @key{SPC} to scroll forward one windowful,
        !          5807: or @key{DEL} to scroll backward.  Various other commands are provided for
        !          5808: moving around in the file, but none for changing it; type @kbd{C-h} while
        !          5809: viewing for a list of them.  They are mostly the same as normal Emacs
        !          5810: cursor motion commands.  To exit from viewing, type @kbd{C-c}.
        !          5811: 
        !          5812: @findex insert-file
        !          5813:   @kbd{M-x insert-file} inserts a copy of the contents of the specified
        !          5814: file into the current buffer at point, leaving point unchanged before the
        !          5815: contents and the mark after them.  @xref{Mark}.
        !          5816: 
        !          5817: @findex write-region
        !          5818: @findex append-to-file
        !          5819:   @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it copies
        !          5820: the contents of the region into the specified file.  @kbd{M-x append-to-file}
        !          5821: adds the text of the region to the end of the specified file.
        !          5822: 
        !          5823: @findex delete-file
        !          5824: @cindex deletion (of files)
        !          5825:   @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
        !          5826: command in the shell.  If you are deleting many files in one directory, it
        !          5827: may be more convenient to use Dired (@pxref{Dired}).
        !          5828: 
        !          5829: @findex rename-file
        !          5830:   @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
        !          5831: the minibuffer, then renames file @var{old} as @var{new}.  If a file named
        !          5832: @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
        !          5833: done; this is because renaming causes the old meaning of the name @var{new}
        !          5834: to be lost.  If @var{old} and @var{new} are on different file systems, the
        !          5835: file @var{old} is copied and deleted.
        !          5836: 
        !          5837: @findex add-name-to-file
        !          5838:   The similar command @kbd{M-x add-name-to-file} is used to add an
        !          5839: additional name to an existing file without removing its old name.
        !          5840: The new name must belong on the same file system that the file is on.
        !          5841: 
        !          5842: @findex copy-file
        !          5843: @cindex copying files
        !          5844:   @kbd{M-x copy-file} reads the file @var{old} and writes a new file named
        !          5845: @var{new} with the same contents.  Confirmation is required if a file named
        !          5846: @var{new} already exists, because copying has the consequence of overwriting
        !          5847: the old contents of the file @var{new}.
        !          5848: 
        !          5849: @findex make-symbolic-link
        !          5850:   @kbd{M-x make-symbolic-link} reads two file names @var{old} and @var{linkname},
        !          5851: and then creates a symbolic link named @var{linkname} and pointing at @var{old}.
        !          5852: The effect is that future attempts to open file @var{linkname} will refer
        !          5853: to whatever file is named @var{old} at the time the opening is done, or
        !          5854: will get an error if the name @var{old} is not in use at that time.
        !          5855: Confirmation is required when creating the link if @var{linkname} is in
        !          5856: use.  Note that not all systems support symbolic links.
        !          5857: 
        !          5858: @node Buffers, Windows, Files, Top
        !          5859: @chapter Using Multiple Buffers
        !          5860: 
        !          5861: @cindex buffers
        !          5862:   The text you are editing in Emacs resides in an object called a
        !          5863: @dfn{buffer}.  Each time you visit a file, a buffer is created to hold the
        !          5864: file's text.  Each time you invoke Dired, a buffer is created to hold the
        !          5865: directory listing.  If you send a message with @kbd{C-x m}, a buffer named
        !          5866: @samp{*mail*} is used to hold the text of the message.  When you ask for a
        !          5867: command's documentation, that appears in a buffer called @file{*Help*}.
        !          5868: 
        !          5869: @cindex selected buffer
        !          5870: @cindex current buffer
        !          5871:   At any time, one and only one buffer is @dfn{selected}.  It is also
        !          5872: called the @dfn{current buffer}.  Often we say that a command operates on
        !          5873: ``the buffer'' as if there were only one; but really this means that the
        !          5874: command operates on the selected buffer (most commands do).
        !          5875: 
        !          5876:   When Emacs makes multiple windows, each window has a chosen buffer which
        !          5877: is displayed there, but at any time only one of the windows is selected and
        !          5878: its chosen buffer is the selected buffer.  Each window's mode line displays
        !          5879: the name of the buffer that the window is displaying (@pxref{Windows}).
        !          5880: 
        !          5881:   Each buffer has a name, which can be of any length, and you can select
        !          5882: any buffer by giving its name.  Most buffers are made by visiting files,
        !          5883: and their names are derived from the files' names.  But you can also create
        !          5884: an empty buffer with any name you want.  A newly started Emacs has a buffer
        !          5885: named @samp{*scratch*} which can be used for evaluating Lisp expressions in
        !          5886: Emacs.  The distinction between upper and lower case matters in buffer
        !          5887: names.
        !          5888: 
        !          5889:   Each buffer records individually what file it is visiting, whether it is
        !          5890: modified, and what major mode and minor modes are in effect in it
        !          5891: (@pxref{Major Modes}).  Any Emacs variable can be made @dfn{local to} a
        !          5892: particular buffer, meaning its value in that buffer can be different from
        !          5893: the value in other buffers.  @xref{Locals}.
        !          5894: 
        !          5895: @menu
        !          5896: * Select Buffer::   Creating a new buffer or reselecting an old one.
        !          5897: * List Buffers::    Getting a list of buffers that exist.
        !          5898: * Misc Buffer::     Renaming; changing read-onliness; copying text.
        !          5899: * Kill Buffer::     Killing buffers you no longer need.
        !          5900: * Several Buffers:: How to go through the list of all buffers
        !          5901:                      and operate variously on several of them.
        !          5902: @end menu
        !          5903: 
        !          5904: @node Select Buffer, List Buffers, Buffers, Buffers
        !          5905: @section Creating and Selecting Buffers
        !          5906: @cindex change buffers
        !          5907: @cindex switch buffers
        !          5908: 
        !          5909: @table @kbd
        !          5910: @item C-x b @var{buffer} @key{RET}
        !          5911: Select or create a buffer named @var{buffer} (@code{switch-to-buffer}).
        !          5912: @item C-x 4 b @var{buffer} @key{RET}
        !          5913: Similar, but select a buffer named @var{buffer} in another window
        !          5914: (@code{switch-to-buffer-other-window}).
        !          5915: @end table
        !          5916: 
        !          5917: @kindex C-x 4 b
        !          5918: @c @findex switch-to-buffer-other-window
        !          5919: @kindex C-x b
        !          5920: @findex switch-to-buffer
        !          5921:   To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname}
        !          5922: @key{RET}}.  This is the command @code{switch-to-buffer} with argument
        !          5923: @var{bufname}.  You can use completion on an abbreviation for the buffer
        !          5924: name you want (@pxref{Completion}).  An empty argument to @kbd{C-x b}
        !          5925: specifies the most recently selected buffer that is not displayed in any
        !          5926: window.@refill
        !          5927: 
        !          5928:   Most buffers are created by visiting files, or by Emacs commands that
        !          5929: want to display some text, but you can also create a buffer explicitly by
        !          5930: typing @kbd{C-x b @var{bufname} @key{RET}}.  This makes a new, empty buffer which
        !          5931: is not visiting any file, and selects it for editing.  Such buffers are
        !          5932: used for making notes to yourself.  If you try to save one, you are asked
        !          5933: for the file name to use.  The new buffer's major mode is determined by the
        !          5934: value of @code{default-major-mode} (@pxref{Major Modes}).
        !          5935: 
        !          5936:   Note that @kbd{C-x C-f}, and any other command for visiting a file, can
        !          5937: also be used to switch buffers.  @xref{Visiting}.
        !          5938: 
        !          5939: @node List Buffers, Misc Buffer, Select Buffer, Buffers
        !          5940: @section Listing Existing Buffers
        !          5941: 
        !          5942: @table @kbd
        !          5943: @item C-x C-b
        !          5944: List the existing buffers (@code{list-buffers}).
        !          5945: @end table
        !          5946: 
        !          5947: @kindex C-x C-b
        !          5948: @findex list-buffers
        !          5949:   To print a list of all the buffers that exist, type @kbd{C-x C-b}.
        !          5950: Each line in the list shows one buffer's name, major mode and visited file.
        !          5951: @samp{*} at the beginning of a line indicates the buffer is ``modified''.
        !          5952: If several buffers are modified, it may be time to save some with @kbd{C-x
        !          5953: s} (@pxref{Saving}).  @samp{%} indicates a read-only buffer.  @samp{.}
        !          5954: marks the selected buffer.  Here is an example of a buffer list:@refill
        !          5955: 
        !          5956: @smallexample
        !          5957:  MR Buffer         Size  Mode           File
        !          5958:  -- ------         ----  ----           ----
        !          5959: .*  emacs.tex      383402 Texinfo       /u2/emacs/man/emacs.tex
        !          5960:     *Help*         1287  Fundamental   
        !          5961:     files.el       23076 Emacs-Lisp     /u2/emacs/lisp/files.el
        !          5962:   % RMAIL          64042 RMAIL          /u/rms/RMAIL
        !          5963:  *% man            747   Dired         
        !          5964:     net.emacs      343885 Fundamental   /u/rms/net.emacs
        !          5965:     fileio.c       27691 C              /u2/emacs/src/fileio.c
        !          5966:     NEWS           67340 Text           /u2/emacs/etc/NEWS
        !          5967:     *scratch*     0     Lisp Interaction
        !          5968: @end smallexample
        !          5969: 
        !          5970: @noindent
        !          5971: Note that the buffer @file{*Help*} was made by a help request; it is not
        !          5972: visiting any file.  The buffer @file{man} was made by Dired on the
        !          5973: directory @file{/u2/emacs/man/}.
        !          5974: 
        !          5975: @node Misc Buffer, Kill Buffer, List Buffers, Buffers
        !          5976: @section Miscellaneous Buffer Operations
        !          5977: 
        !          5978: @table @kbd
        !          5979: @item C-x C-q
        !          5980: Toggle read-only status of buffer (@code{toggle-read-only}).
        !          5981: @item M-x rename-buffer
        !          5982: Change the name of the current buffer.
        !          5983: @item M-x view-buffer
        !          5984: Scroll through a buffer.
        !          5985: @end table
        !          5986: 
        !          5987: @cindex read-only buffer
        !          5988: @kindex C-x C-q
        !          5989: @findex toggle-read-only
        !          5990: @vindex buffer-read-only
        !          5991:   A buffer can be @dfn{read-only}, which means that commands to change its
        !          5992: text are not allowed.  Normally, read-only buffers are made by subsystems
        !          5993: such as Dired and Rmail that have special commands to operate on the text;
        !          5994: a read-only buffer is also made if you visit a file that is protected so
        !          5995: you cannot write it.  If you wish to make changes in a read-only buffer,
        !          5996: use the command @kbd{C-x C-q} (@code{toggle-read-only}).  It makes a
        !          5997: read-only buffer writable, and makes a writable buffer read-only.  This
        !          5998: works by setting the variable @code{buffer-read-only}, which has a local
        !          5999: value in each buffer and makes the buffer read-only if its value is
        !          6000: non-@code{nil}.
        !          6001: 
        !          6002: @findex rename-buffer
        !          6003:   @kbd{M-x rename-buffer} changes the name of the current buffer.  Specify
        !          6004: the new name as a minibuffer argument.  There is no default.  If you
        !          6005: specify a name that is in use for some other buffer, an error happens and
        !          6006: no renaming is done.
        !          6007: 
        !          6008: @findex view-buffer
        !          6009: @cindex View mode
        !          6010:   @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc File Ops})
        !          6011: except that it examines an already existing Emacs buffer.  View mode
        !          6012: provides commands for scrolling through the buffer conveniently but not
        !          6013: for changing it. When you exit View mode, the value of point that resulted
        !          6014: from your perusal remains in effect.
        !          6015: 
        !          6016:   The commands @kbd{C-x a} (@code{append-to-buffer}) and @kbd{M-x
        !          6017: insert-buffer} can be used to copy text from one buffer to another.
        !          6018: @xref{Accumulating Text}.@refill
        !          6019: 
        !          6020: @node Kill Buffer, Several Buffers, Misc Buffer, Buffers
        !          6021: @section Killing Buffers
        !          6022: 
        !          6023:   After you use Emacs for a while, you may accumulate a large number of
        !          6024: buffers.  You may then find it convenient to eliminate the ones you no
        !          6025: longer need.  There are several commands provided for doing this.
        !          6026: 
        !          6027: @c WideCommands
        !          6028: @table @kbd
        !          6029: @item C-x k
        !          6030: Kill a buffer, specified by name (@code{kill-buffer}).
        !          6031: @item M-x kill-some-buffers
        !          6032: Offer to kill each buffer, one by one.
        !          6033: @end table
        !          6034: 
        !          6035: @findex kill-buffer
        !          6036: @findex kill-some-buffers
        !          6037: @kindex C-x k
        !          6038: 
        !          6039:   @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you specify
        !          6040: in the minibuffer.  The default, used if you type just @key{RET} in the
        !          6041: minibuffer, is to kill the current buffer.  If the current buffer is
        !          6042: killed, another buffer is selected; a buffer that has been selected
        !          6043: recently but does not appear in any window now is chosen to be selected.
        !          6044: If the buffer being killed is modified (has unsaved editing) then you are
        !          6045: asked to confirm with @kbd{yes} before the buffer is killed.
        !          6046: 
        !          6047:   The command @kbd{M-x kill-some-buffers} asks about each buffer, one by
        !          6048: one.  An answer of @kbd{y} means to kill the buffer.  Killing the current
        !          6049: buffer or a buffer containing unsaved changes selects a new buffer or asks
        !          6050: for confirmation just like @code{kill-buffer}.
        !          6051: 
        !          6052: @node Several Buffers,, Kill Buffer, Buffers
        !          6053: @section Operating on Several Buffers
        !          6054: @cindex buffer menu
        !          6055: 
        !          6056:   The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows
        !          6057: you to request operations on various Emacs buffers by editing an Emacs
        !          6058: buffer containing a list of them.  You can save buffers, kill them
        !          6059: (here called @dfn{deleting} them, for consistency with Dired), or display
        !          6060: them.
        !          6061: 
        !          6062: @table @kbd
        !          6063: @item M-x buffer-menu
        !          6064: Begin editing a buffer listing all Emacs buffers.
        !          6065: @end table
        !          6066: 
        !          6067: @findex buffer-menu
        !          6068: @cindex Buffer Menu mode
        !          6069:   The command @code{buffer-menu} writes a list of all Emacs buffers into
        !          6070: the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu
        !          6071: mode.  The buffer is read-only, and can only be changed through the special
        !          6072: commands described in this section.  Most of these commands are graphic
        !          6073: characters.  The usual Emacs cursor motion commands can be used in the
        !          6074: @samp{*Buffer List*} buffer.  The following special commands apply to the
        !          6075: buffer described on the current line.
        !          6076: 
        !          6077: @table @kbd
        !          6078: @item d
        !          6079: Request to delete (kill) the buffer, then move down.  The request
        !          6080: shows as a @samp{D} on the line, before the buffer name.  Requested
        !          6081: deletions take place when the @kbd{x} command is used.
        !          6082: @item k
        !          6083: Synonym for @kbd{d}.
        !          6084: @item C-d
        !          6085: Like @kbd{d} but move up afterwards instead of down.
        !          6086: @item s
        !          6087: Request to save the buffer.  The request shows as an @samp{S} on the
        !          6088: line.  Requested saves take place when the @kbd{x} command is used.
        !          6089: You may request both saving and deletion for the same buffer.
        !          6090: @item ~
        !          6091: Mark buffer ``unmodified''.  The command @kbd{~} does this
        !          6092: immediately when typed.
        !          6093: @item x
        !          6094: Perform previously requested deletions and saves.
        !          6095: @item u
        !          6096: Remove any request made for the current line, and move down.
        !          6097: @item @key{DEL}
        !          6098: Move to previous line and remove any request made for that line.
        !          6099: @end table
        !          6100: 
        !          6101:   All the commands that put in or remove flags to request later operations
        !          6102: also move down a line, and accept a numeric argument as a repeat count,
        !          6103: unless otherwise specified.
        !          6104: 
        !          6105:   There are also special commands to use the buffer list to select another
        !          6106: buffer, and to specify one or more other buffers for display in additional
        !          6107: windows.
        !          6108: 
        !          6109: @table @kbd
        !          6110: @item 1
        !          6111: Select the buffer in a full-screen window.  This command takes effect
        !          6112: immediately.
        !          6113: @item 2
        !          6114: Immediately set up two windows, with this buffer in one, and the
        !          6115: previously selected buffer (aside from the buffer @samp{*Buffer List*})
        !          6116: in the other.
        !          6117: @item f
        !          6118: Immediately select the buffer in place of the @samp{*Buffer List*} buffer.
        !          6119: @item o
        !          6120: Immediately select the buffer in another window as if by @w{@kbd{C-x 4 b}},
        !          6121: leaving @samp{*Buffer List*} visible.
        !          6122: @item q
        !          6123: Immediately select this buffer, and also display in other windows any
        !          6124: buffers previously flagged with the @kbd{m} command.  If there are no
        !          6125: such buffers, this command is equivalent to @kbd{1}.
        !          6126: @item m
        !          6127: Flag this buffer to be displayed in another window if the @kbd{q}
        !          6128: command is used.  The request shows as a @samp{>} at the beginning of
        !          6129: the line.  The same buffer may not have both a delete request and a
        !          6130: display request.
        !          6131: @end table
        !          6132: 
        !          6133:   All that @code{buffer-menu} does directly is create and select a suitable
        !          6134: buffer, and turn on Buffer Menu mode.  Everything else described above is
        !          6135: implemented by the special commands provided in Buffer Menu mode.  One
        !          6136: consequence of this is that you can switch from the @samp{*Buffer List*}
        !          6137: buffer to another Emacs buffer, and edit there.  You can reselect the
        !          6138: @code{buffer-menu} buffer later, to perform the operations already
        !          6139: requested, or you can kill it, or pay no further attention to it.
        !          6140: 
        !          6141:   The only difference between @code{buffer-menu} and @code{list-buffers} is
        !          6142: that @code{buffer-menu} selects the @samp{*Buffer List*} buffer and
        !          6143: @code{list-buffers} does not.  If you run @code{list-buffers} (that is,
        !          6144: type @kbd{C-x C-b}) and select the buffer list manually, you can use all of
        !          6145: the commands described here.
        !          6146: 
        !          6147: @node Windows, Major Modes, Buffers, Top
        !          6148: @chapter Multiple Windows
        !          6149: @cindex windows
        !          6150: 
        !          6151:   Emacs can split the screen into two or many windows, which can display
        !          6152: parts of different buffers, or different parts of one buffer.
        !          6153: 
        !          6154: @menu
        !          6155: * Basic Window::     Introduction to Emacs windows.
        !          6156: * Split Window::     New windows are made by splitting existing windows.
        !          6157: * Other Window::     Moving to another window or doing something to it.
        !          6158: * Pop Up Window::    Finding a file or buffer in another window.
        !          6159: * Change Window::    Deleting windows and changing their sizes.
        !          6160: @end menu
        !          6161: 
        !          6162: @node Basic Window, Split Window, Windows, Windows
        !          6163: @section Concepts of Emacs Windows
        !          6164: 
        !          6165:   When multiple windows are being displayed, each window has an Emacs
        !          6166: buffer designated for display in it.  The same buffer may appear in more
        !          6167: than one window; if it does, any changes in its text are displayed in all
        !          6168: the windows where it appears.  But the windows showing the same buffer can
        !          6169: show different parts of it, because each window has its own value of point.
        !          6170: 
        !          6171: @cindex selected window
        !          6172:   At any time, one of the windows is the @dfn{selected window}; the buffer
        !          6173: this window is displaying is the current buffer.  The terminal's cursor
        !          6174: shows the location of point in this window.  Each other window has a
        !          6175: location of point as well, but since the terminal has only one cursor there
        !          6176: is no way to show where those locations are.
        !          6177: 
        !          6178:   Commands to move point affect the value of point for the selected Emacs
        !          6179: window only.  They do not change the value of point in any other Emacs
        !          6180: window, even one showing the same buffer.  The same is true for commands
        !          6181: such as @kbd{C-x b} to change the selected buffer in the selected window;
        !          6182: they do not affect other windows at all.  However, there are other commands
        !          6183: such as @kbd{C-x 4 b} that select a different window and switch buffers in
        !          6184: it.  Also, all commands that display information in a window, including
        !          6185: (for example) @w{@kbd{C-h f}} (@code{describe-function}) and @kbd{C-x C-b}
        !          6186: (@code{list-buffers}), work by switching buffers in a nonselected window
        !          6187: without affecting the selected window.
        !          6188: 
        !          6189:   Each window has its own mode line, which displays the buffer name,
        !          6190: modification status and major and minor modes of the buffer that is
        !          6191: displayed in the window.  @xref{Mode Line}, for full details on the mode
        !          6192: line.
        !          6193: 
        !          6194: @node Split Window, Other Window, Basic Window, Windows
        !          6195: @section Splitting Windows
        !          6196: 
        !          6197: @table @kbd
        !          6198: @item C-x 2
        !          6199: Split the selected window into two windows, one above the other
        !          6200: (@code{split-window-vertically}).
        !          6201: @item C-x 5
        !          6202: Split the selected window into two windows positioned side by side
        !          6203: (@code{split-window-horizontally}).
        !          6204: @end table
        !          6205: 
        !          6206: @kindex C-x 2
        !          6207: @findex split-window-vertically
        !          6208:   The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the
        !          6209: selected window into two windows, one above the other.  Both windows start
        !          6210: out displaying the same buffer, with the same value of point.  By default
        !          6211: the two windows each get half the height of the window that was split; a
        !          6212: numeric argument specifies how many lines to give to the top window.
        !          6213: 
        !          6214: @kindex C-x 5
        !          6215: @findex split-window-horizontally
        !          6216:   @kbd{C-x 5} (@code{split-window-horizontally}) breaks the selected
        !          6217: window into two side-by-side windows.  A numeric argument specifies
        !          6218: how many columns to give the one on the left.  A line of vertical bars
        !          6219: separates the two windows.  Windows that are not the full width of the
        !          6220: screen have mode lines, but they are truncated; also, they do not
        !          6221: always appear in inverse video, because, the Emacs display routines
        !          6222: have not been taught how to display a region of inverse video that is
        !          6223: only part of a line on the screen.
        !          6224: 
        !          6225: @vindex truncate-partial-width-windows
        !          6226:   When a window is less than the full width, text lines too long to fit are
        !          6227: frequent.  Continuing all those lines might be confusing.  The variable
        !          6228: @code{truncate-partial-width-windows} can be set non-@code{nil} to force
        !          6229: truncation in all windows less than the full width of the screen,
        !          6230: independent of the buffer being displayed and its value for
        !          6231: @code{truncate-lines}.  @xref{Continuation Lines}.@refill
        !          6232: 
        !          6233:   Horizontal scrolling is often used in side-by-side windows.
        !          6234: @xref{Display}.
        !          6235: 
        !          6236: @node Other Window, Pop Up Window, Split Window, Windows
        !          6237: @section Using Other Windows
        !          6238: 
        !          6239: @table @kbd
        !          6240: @item C-x o
        !          6241: Select another window (@code{other-window}).  That is @kbd{o}, not zero.
        !          6242: @item C-M-v
        !          6243: Scroll the next window (@code{scroll-other-window}).
        !          6244: @item M-x compare-windows
        !          6245: Find next place where the text in the selected window does not match
        !          6246: the text in the next window.
        !          6247: @end table
        !          6248: 
        !          6249: @kindex C-x o
        !          6250: @findex other-window
        !          6251:   To select a different window, use @kbd{C-x o} (@code{other-window}).
        !          6252: That is an @kbd{o}, for `other', not a zero.  When there are more than two
        !          6253: windows, this command moves through all the windows in a cyclic order,
        !          6254: generally top to bottom and left to right.  From the rightmost and
        !          6255: bottommost window, it goes back to the one at the upper left corner.  A
        !          6256: numeric argument means to move several steps in the cyclic order of
        !          6257: windows.  A negative argument moves around the cycle in the opposite order.
        !          6258: When the minibuffer is active, the minibuffer is the last window in the
        !          6259: cycle; you can switch from the minibuffer window to one of the other
        !          6260: windows, and later switch back and finish supplying the minibuffer argument
        !          6261: that is requested.  @xref{Minibuffer Edit}.
        !          6262: 
        !          6263: @kindex C-M-v
        !          6264: @findex scroll-other-window
        !          6265:   The usual scrolling commands (@pxref{Display}) apply to the selected
        !          6266: window only, but there is one command to scroll the next window.
        !          6267: @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that @w{@kbd{C-x o}}
        !          6268: would select.  It takes arguments, positive and negative, like @kbd{C-v}.
        !          6269: 
        !          6270: @findex compare-windows
        !          6271:   The command @kbd{M-x compare-windows} compares the text in the current
        !          6272: window with that in the next window.  Comparison starts at point in each
        !          6273: window.  Point moves forward in each window, a character at a time in each
        !          6274: window, until the next characters in the two windows are different.  Then
        !          6275: the command is finished.
        !          6276: 
        !          6277: @node Pop Up Window, Change Window, Other Window, Windows
        !          6278: @section Displaying in Another Window
        !          6279: 
        !          6280: @kindex C-x 4
        !          6281:   @kbd{C-x 4} is a prefix key for commands that select another window
        !          6282: (splitting the window if there is only one) and select a buffer in that
        !          6283: window.  Different @kbd{C-x 4} commands have different ways of finding the
        !          6284: buffer to select.
        !          6285: 
        !          6286: @findex switch-to-buffer-other-window
        !          6287: @findex find-file-other-window
        !          6288: @findex find-tag-other-window
        !          6289: @findex dired-other-window
        !          6290: @findex mail-other-window
        !          6291: @table @kbd
        !          6292: @item C-x 4 b @var{bufname} @key{RET}
        !          6293: Select buffer @var{bufname} in another window.  This runs 
        !          6294: @code{switch-to-buffer-other-window}.
        !          6295: @item C-x 4 f @var{filename} @key{RET}
        !          6296: Visit file @var{filename} and select its buffer in another window.  This
        !          6297: runs @code{find-file-other-window}.  @xref{Visiting}.
        !          6298: @item C-x 4 d @var{directory} @key{RET}
        !          6299: Select a Dired buffer for directory @var{directory} in another window.
        !          6300: This runs @code{dired-other-window}.  @xref{Dired}.
        !          6301: @item C-x 4 m
        !          6302: Start composing a mail message in another window.  This runs
        !          6303: @code{mail-other-window}, and its same-window version is @kbd{C-x m}
        !          6304: (@pxref{Sending Mail}).
        !          6305: @item C-x 4 .
        !          6306: Find a tag in the current tag table in another window.  This runs
        !          6307: @code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
        !          6308: (@pxref{Tags}).
        !          6309: @end table
        !          6310: 
        !          6311: @node Change Window,, Pop Up Window, Windows
        !          6312: @section Deleting and Rearranging Windows
        !          6313: 
        !          6314: @table @kbd
        !          6315: @item C-x 0
        !          6316: Get rid of the selected window (@code{kill-window}).  That is a zero.
        !          6317: @item C-x 1
        !          6318: Get rid of all windows except the selected one (@code{delete-other-windows}).
        !          6319: @item C-x ^
        !          6320: Make the selected window taller, at the expense of the other(s)
        !          6321: (@code{enlarge-window}).
        !          6322: @item C-x @}
        !          6323: Widen the selected window (@code{enlarge-window-horizontally}).
        !          6324: @end table
        !          6325: 
        !          6326: @kindex C-x 0
        !          6327: @findex delete-window
        !          6328:   To delete a window, type @kbd{C-x 0} (@code{delete-window}).  (That is a
        !          6329: zero.)  The space occupied by the deleted window is distributed among the
        !          6330: other active windows (but not the minibuffer window, even if that is active
        !          6331: at the time).  Once a window is deleted, its attributes are forgotten;
        !          6332: there is no automatic way to make another window of the same shape or
        !          6333: showing the same buffer.  But the buffer continues to exist, and you can
        !          6334: select it in any window with @kbd{C-x b}.
        !          6335: 
        !          6336: @kindex C-x 1
        !          6337: @findex delete-other-windows
        !          6338:   @kbd{C-x 1} (@code{delete-other-windows}) is more powerful than @kbd{C-x 0};
        !          6339: it deletes all the windows except the selected one (and the minibuffer);
        !          6340: the selected window expands to use the whole screen except for the echo
        !          6341: area.
        !          6342: 
        !          6343: @kindex C-x ^
        !          6344: @findex enlarge-window
        !          6345: @kindex C-x @}
        !          6346: @findex enlarge-window-horizontally
        !          6347: @vindex window-min-height
        !          6348: @vindex window-min-width
        !          6349:   To readjust the division of space among existing windows, use @kbd{C-x ^}
        !          6350: (@code{enlarge-window}).  It makes the currently selected window get one
        !          6351: line bigger, or as many lines as is specified with a numeric argument.
        !          6352: With a negative argument, it makes the selected window smaller.  @kbd{C-x
        !          6353: @}} (@code{enlarge-window-horizontally}) makes the selected window wider
        !          6354: by the specified number of columns.  The extra screen space given to a
        !          6355: window comes from one of its neighbors, if that is possible; otherwise, all
        !          6356: the competing windows are shrunk in the same proportion.  If this makes any
        !          6357: windows too small, those windows are deleted and their space is divided up.
        !          6358: The minimum size is specified by the variables @code{window-min-height} and
        !          6359: @code{window-min-width}.
        !          6360: 
        !          6361: @node Major Modes, Indentation, Windows, Top
        !          6362: @chapter Major Modes
        !          6363: @cindex major modes
        !          6364: @kindex TAB
        !          6365: @kindex DEL
        !          6366: @kindex LFD
        !          6367: 
        !          6368:   Emacs has many different @dfn{major modes}, each of which customizes
        !          6369: Emacs for editing text of a particular sort.  The major modes are mutually
        !          6370: exclusive, and each buffer has one major mode at any time.  The mode line
        !          6371: normally contains the name of the current major mode, in parentheses.
        !          6372: @xref{Mode Line}.
        !          6373: 
        !          6374:   The least specialized major mode is called @dfn{Fundamental mode}.  This
        !          6375: mode has no mode-specific redefinitions or variable settings, so that each
        !          6376: Emacs command behaves in its most general manner, and each option is in its
        !          6377: default state.  For editing any specific type of text, such as Lisp code or
        !          6378: English text, you should switch to the appropriate major mode, such as Lisp
        !          6379: mode or Text mode.
        !          6380: 
        !          6381:   Selecting a major mode changes the meanings of a few keys to become more
        !          6382: specifically adapted to the language being edited.  The ones which are
        !          6383: changed frequently are @key{TAB}, @key{DEL}, and @key{LFD}.  In addition,
        !          6384: the commands which handle comments use the mode to determine how comments
        !          6385: are to be delimited.  Many major modes redefine the syntactical properties
        !          6386: of characters appearing in the buffer.  @xref{Syntax}.
        !          6387: 
        !          6388:   The major modes fall into three major groups.  Lisp mode (which has
        !          6389: several variants), C mode and Muddle mode are for specific programming
        !          6390: languages.  Text mode, Nroff mode, @TeX{} mode and Outline mode are for
        !          6391: editing English text.  The remaining major modes are not intended for use
        !          6392: on users' files; they are used in buffers created for specific purposes by
        !          6393: Emacs, such as Dired mode for buffers made by Dired (@pxref{Dired}), and
        !          6394: Mail mode for buffers made by @kbd{C-x m} (@pxref{Sending Mail}), and Shell
        !          6395: mode for buffers used for communicating with an inferior shell process
        !          6396: (@pxref{Interactive Shell}).
        !          6397: 
        !          6398:   Most programming language major modes specify that only blank lines
        !          6399: separate paragraphs.  This is so that the paragraph commands remain useful.
        !          6400: @xref{Paragraphs}.  They also cause Auto Fill mode to use the definition of
        !          6401: @key{TAB} to indent the new lines it creates.  This is because most lines
        !          6402: in a program are usually indented.  @xref{Indentation}.
        !          6403: 
        !          6404: @menu
        !          6405: * Choosing Modes::     How major modes are specified or chosen.
        !          6406: @end menu
        !          6407: 
        !          6408: @node Choosing Modes,,Major Modes,Major Modes
        !          6409: @section How Major Modes are Chosen
        !          6410: @cindex mode selection
        !          6411: @cindex selection of mode
        !          6412: @cindex choosing a mode
        !          6413: 
        !          6414:   You can select a major mode explicitly for the current buffer, but
        !          6415: most of the time Emacs determines which mode to use based on the file
        !          6416: name or some text in the file.
        !          6417: 
        !          6418:   Explicit selection of a new major mode is done with a @kbd{M-x} command.
        !          6419: From the name of a major mode, add @code{-mode} to get the name of a
        !          6420: command to select that mode.  Thus, you can enter Lisp mode by executing
        !          6421: @kbd{M-x lisp-mode}.
        !          6422: 
        !          6423: @vindex auto-mode-alist
        !          6424:   When you visit a file, Emacs usually chooses the right major mode based
        !          6425: on the file's name.  For example, files whose names end in @code{.c} are
        !          6426: edited in C mode.  The correspondence between file names and major mode is
        !          6427: controlled by the variable @code{auto-mode-alist}.  Its value is a list in
        !          6428: which each element has the form
        !          6429: 
        !          6430: @example
        !          6431: (@var{regexp} . @var{mode-function})
        !          6432: @end example
        !          6433: 
        !          6434: @noindent
        !          6435: For example, one element normally found in the list has the form
        !          6436: @code{(@t{"\\.c$"} . c-mode)}, and it is responsible for selecting C mode
        !          6437: for files whose names end in @file{.c}.  (Note that @samp{\\} is needed in
        !          6438: Lisp syntax to include a @samp{\} in the string, which is needed to
        !          6439: suppress the special meaning of @samp{.} in regexps.)  The only practical
        !          6440: way to change this variable is with Lisp code.
        !          6441: 
        !          6442:   You can specify which major mode should be used for editing a certain
        !          6443: file by a special sort of text in the first nonblank line of the file.  The
        !          6444: mode name should appear in this line both preceded and followed by
        !          6445: @samp{-*-}.  Other text may appear on the line as well.  For example,
        !          6446: 
        !          6447: @example
        !          6448: ;-*-Lisp-*-
        !          6449: @end example
        !          6450: 
        !          6451: @noindent
        !          6452: tells Emacs to use Lisp mode.  Note how the semicolon is used to make Lisp
        !          6453: treat this line as a comment.  Such an explicit specification overrides any
        !          6454: defaulting based on the file name.
        !          6455: 
        !          6456:   Another format of mode specification is
        !          6457: 
        !          6458: @example
        !          6459: -*-Mode: @var{modename};-*-
        !          6460: @end example
        !          6461: 
        !          6462: @noindent
        !          6463: which allows other things besides the major mode name to be specified.
        !          6464: However, Emacs does not look for anything except the mode name.
        !          6465: 
        !          6466: The major mode can also be specified in a local variables list.
        !          6467: @xref{File Variables}.
        !          6468: 
        !          6469: @vindex default-major-mode
        !          6470:   When a file is visited that does not specify a major mode to use, or when
        !          6471: a new buffer is created with @kbd{C-x b}, the major mode used is that
        !          6472: specified by the variable @code{default-major-mode}.  Normally this value
        !          6473: is the symbol @code{fundamental-mode}, which specifies Fundamental mode.
        !          6474: If @code{default-major-mode} is @code{nil}, the major mode is taken from
        !          6475: the previously selected buffer.
        !          6476: 
        !          6477: @findex normal-mode
        !          6478:   The command @kbd{M-x normal-mode} recalculates the major mode from the
        !          6479: visited file name and the contents of the buffer.
        !          6480: 
        !          6481: @node Indentation, Text, Major Modes, Top
        !          6482: @chapter Indentation
        !          6483: @cindex indentation
        !          6484: 
        !          6485: @c WideCommands
        !          6486: @table @kbd
        !          6487: @item @key{TAB}
        !          6488: Indent current line ``appropriately'' in a mode-dependent fashion.
        !          6489: @item @key{LFD}
        !          6490: Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
        !          6491: @item M-^
        !          6492: Merge two lines (@code{delete-indentation}).  This would cancel out
        !          6493: the effect of @key{LFD}.
        !          6494: @item C-M-o
        !          6495: Split line at point; text on the line after point becomes a new line
        !          6496: indented to the same column that it now starts in (@code{split-line}).
        !          6497: @item M-m
        !          6498: Move (forward or back) to the first nonblank character on the current
        !          6499: line (@code{back-to-indentation}).
        !          6500: @item C-M-\
        !          6501: Indent several lines to same column (@code{indent-region}).
        !          6502: @item C-x @key{TAB}
        !          6503: Shift block of lines rigidly right or left (@code{indent-rigidly}).
        !          6504: @item M-i
        !          6505: Indent from point to the next prespecified tab stop column
        !          6506: (@code{tab-to-tab-stop}).
        !          6507: @item M-x indent-relative
        !          6508: Indent from point to under an indentation point in the previous line.
        !          6509: @end table
        !          6510: 
        !          6511: @kindex TAB
        !          6512: @cindex indentation
        !          6513:   Most programming languages have some indentation convention.  For Lisp
        !          6514: code, lines are indented according to their nesting in parentheses.  The
        !          6515: same general idea is used for C code, though many details are different.
        !          6516: 
        !          6517:   Whatever the language, to indent a line, use the @key{TAB} command.  Each
        !          6518: major mode defines this command to perform the sort of indentation
        !          6519: appropriate for the particular language.  In Lisp mode, @key{TAB} aligns
        !          6520: the line according to its depth in parentheses.  No matter where in the
        !          6521: line you are when you type @key{TAB}, it aligns the line as a whole.  In C
        !          6522: mode, @key{TAB} implements a subtle and sophisticated indentation style that
        !          6523: knows about many aspects of C syntax.
        !          6524: 
        !          6525: @kindex TAB
        !          6526:   In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which
        !          6527: indents to the next tab stop column.  You can set the tab stops with
        !          6528: @kbd{M-x edit-tab-stops}.
        !          6529: 
        !          6530: @menu
        !          6531: * Indentation Commands:: Various commands and techniques for indentation.
        !          6532: * Tab Stops::            You can set arbitrary "tab stops" and then
        !          6533:                          indent to the next tab stop when you want to.
        !          6534: * Just Spaces::          You can request indentation using just spaces.
        !          6535: @end menu
        !          6536: 
        !          6537: @node Indentation Commands, Tab Stops, Indentation, Indentation
        !          6538: @section Indentation Commands and Techniques
        !          6539: @c ??? Explain what Emacs has instead of space-indent-flag.
        !          6540: 
        !          6541:   If you just want to insert a tab character in the buffer, you can type
        !          6542: @kbd{C-q @key{TAB}}.
        !          6543: 
        !          6544: @kindex M-m
        !          6545: @findex back-to-indentation
        !          6546: @c !!! rewrote to prevent overfull hbox
        !          6547:   To move over the indentation on a line, type @kbd{Meta-m}.  
        !          6548: This command, given anywhere on a line,
        !          6549: positions point at the first nonblank character on the line
        !          6550: (@code{back-to-indentation}).
        !          6551: 
        !          6552:   To insert an indented line before the current line, do @kbd{C-a C-o
        !          6553: @key{TAB}}.  To make an indented line after the current line, use @kbd{C-e
        !          6554: @key{LFD}}.
        !          6555: 
        !          6556: @kindex C-M-o
        !          6557: @findex split-line
        !          6558:   @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of
        !          6559: the line vertically down, so that the current line becomes two lines.
        !          6560: @kbd{C-M-o} first moves point forward over any spaces and tabs.  Then it
        !          6561: inserts after point a newline and enough indentation to reach the same
        !          6562: column point is on.  Point remains before the inserted newline; in this
        !          6563: regard, @kbd{C-M-o} resembles @kbd{C-o}.
        !          6564: 
        !          6565: @kindex M-\
        !          6566: @kindex M-^
        !          6567: @findex delete-horizontal-space
        !          6568: @findex delete-indentation
        !          6569:   To join two lines cleanly, use the @kbd{Meta-^}
        !          6570: (@code{delete-indentation}) command to delete the indentation at the
        !          6571: front of the current line, and the line boundary as well.  They are
        !          6572: replaced by a single space, or by no space if point after joining is at
        !          6573: the beginning of a line or before a @samp{)} or after a @samp{(}.  To
        !          6574: delete just the indentation of a line, go to the beginning of the line
        !          6575: and use @kbd{Meta-\} (@code{delete-horizontal-space}), which deletes all
        !          6576: spaces and tabs around the cursor.
        !          6577: 
        !          6578: @kindex C-M-\
        !          6579: @kindex C-x TAB
        !          6580: @findex indent-region
        !          6581: @findex indent-rigidly
        !          6582:   There are also commands for changing the indentation of several lines at
        !          6583: once.  @kbd{Control-Meta-\} (@code{indent-region}) gives each line which
        !          6584: begins in the region the ``usual'' indentation by invoking @key{TAB} at the
        !          6585: beginning of the line.  A numeric argument specifies the column to indent
        !          6586: to, and each line is shifted left or right so that its first nonblank
        !          6587: character appears in that column.  @kbd{C-x @key{TAB}}
        !          6588: (@code{indent-rigidly}) moves all of the lines in the region right by its
        !          6589: argument (left, for negative arguments).  The whole group of lines moves
        !          6590: rigidly sideways, which is how the command gets its name.@refill
        !          6591: 
        !          6592: @findex indent-relative
        !          6593:   @kbd{M-x indent-relative} indents at point based on the previous line
        !          6594: (actually, the last nonempty line.)  It inserts whitespace at point, moving
        !          6595: point, until it is underneath an indentation point in the previous line.
        !          6596: An indentation point is the end of a sequence of whitespace or the end of
        !          6597: the line.  If point is farther right than any indentation point in the
        !          6598: previous line, the whitespace before point is deleted and the first
        !          6599: indentation point then applicable is used.  If no indentation point is
        !          6600: applicable even then, @code{tab-to-tab-stop} is run (see next section).
        !          6601: 
        !          6602:   @code{indent-relative} is the definition of @key{TAB} in Indented Text
        !          6603: mode.  @xref{Text}.
        !          6604: 
        !          6605: @node Tab Stops, Just Spaces, Indentation Commands, Indentation
        !          6606: @section Tab Stops
        !          6607: 
        !          6608: @kindex M-i
        !          6609: @findex tab-to-tab-stop
        !          6610:   For typing in tables, you can use Text mode's definition of @key{TAB},
        !          6611: @code{tab-to-tab-stop}.  This command inserts indentation before point,
        !          6612: enough to reach the next tab stop column.  If you are not in Text mode,
        !          6613: this function can be found on @kbd{M-i} anyway.
        !          6614: 
        !          6615: @findex edit-tab-stops
        !          6616: @findex edit-tab-stops-note-changes
        !          6617: @kindex C-c C-c (Edit Tab Stops)
        !          6618: @vindex tab-stop-list
        !          6619:   The tab stops used by @kbd{M-i} can be set arbitrarily by the user.
        !          6620: They are stored in a variable called @code{tab-stop-list}, as a list of
        !          6621: column-numbers in increasing order.
        !          6622: 
        !          6623:   The convenient way to set the tab stops is using @kbd{M-x edit-tab-stops},
        !          6624: which creates and selects a buffer containing a description of the tab stop
        !          6625: settings.  You can edit this buffer to specify different tab stops, and
        !          6626: then type @kbd{C-c C-c} to make those new tab stops take effect.  In the
        !          6627: tab stop buffer, @w{@kbd{C-c C-c}} runs the function
        !          6628: @code{edit-tab-stops-note-changes} rather than its usual definition
        !          6629: @code{save-buffer}.  @code{edit-tab-stops} records which buffer was current
        !          6630: when you invoked it, and stores the tab stops back in that buffer; normally
        !          6631: all buffers share the same tab stops and changing them in one buffer
        !          6632: affects all, but if you happen to make @code{tab-stop-list} local in one
        !          6633: buffer then @code{edit-tab-stops} in that buffer will edit the local
        !          6634: settings.
        !          6635: 
        !          6636:   Here is what the text representing the tab stops looks like for ordinary
        !          6637: tab stops every eight columns.
        !          6638: 
        !          6639: @example
        !          6640:         :       :       :       :       :       :
        !          6641: 0         1         2         3         4
        !          6642: 0123456789012345678901234567890123456789012345678
        !          6643: To install changes, type C-c C-c
        !          6644: @end example
        !          6645: 
        !          6646:   The first line contains a colon at each tab stop.  The remaining lines
        !          6647: are present just to help you see where the colons are and know what to do.
        !          6648: 
        !          6649:   Note that the tab stops that control @code{tab-to-tab-stop} have nothing
        !          6650: to do with displaying tab characters in the buffer.  @xref{Display Vars},
        !          6651: for more information on that.
        !          6652: 
        !          6653: @node Just Spaces,, Tab Stops, Indentation
        !          6654: @section Tabs vs. Spaces
        !          6655: 
        !          6656: @vindex indent-tabs-mode
        !          6657:   Emacs normally uses both tabs and spaces to indent lines.  If you prefer,
        !          6658: all indentation can be made from spaces only.  To request this, set
        !          6659: @code{indent-tabs-mode} to @code{nil}.  This is a per-buffer variable;
        !          6660: altering the variable affects only the current buffer, but there is a
        !          6661: default value which you can change as well.  @xref{Locals}.
        !          6662: 
        !          6663: @findex tabify
        !          6664: @findex untabify
        !          6665:   There are also commands to convert tabs to spaces or vice versa, always
        !          6666: preserving the columns of all nonblank text.  @kbd{M-x tabify} scans the
        !          6667: region for sequences of spaces, and converts sequences of at least three
        !          6668: spaces to tabs if that can be done without changing indentation.  @kbd{M-x
        !          6669: untabify} changes all tabs in the region to appropriate numbers of spaces.
        !          6670: 
        !          6671: @node Text, Programs, Indentation, Top
        !          6672: @chapter Commands for Human Languages
        !          6673: @cindex text
        !          6674: 
        !          6675:   The term @dfn{text} has two widespread meanings in our area of the
        !          6676: computer field.  One is data that is a sequence of characters.  Any file
        !          6677: that you edit with Emacs is text, in this sense of the word.  The other
        !          6678: meaning is more restrictive: a sequence of characters in a human language
        !          6679: for humans to read (possibly after processing by a text formatter), as
        !          6680: opposed to a program or commands for a program.
        !          6681: 
        !          6682:   Human languages have syntactic/stylistic conventions that can be
        !          6683: supported or used to advantage by editor commands: conventions involving
        !          6684: words, sentences, paragraphs, and capital letters.  This chapter describes
        !          6685: Emacs commands for all of these things.  There are also commands for
        !          6686: @dfn{filling}, or rearranging paragraphs into lines of approximately equal
        !          6687: length.  The commands for moving over and killing words, sentences
        !          6688: and paragraphs, while intended primarily for editing text, are also often
        !          6689: useful for editing programs.
        !          6690: 
        !          6691:   Emacs has several major modes for editing human language text.
        !          6692: If the file contains text pure and simple, use Text mode, which customizes
        !          6693: Emacs in small ways for the syntactic conventions of text.  For text which
        !          6694: contains embedded commands for text formatters, Emacs has other major modes,
        !          6695: each for a particular text formatter.  Thus, for input to @TeX{}, you would
        !          6696: use @TeX{} mode; for input to nroff, Nroff mode.
        !          6697: 
        !          6698: @menu
        !          6699: * Text Mode::   The major modes for editing text files.
        !          6700: * Nroff Mode::  The major mode for editing input to the formatter nroff.
        !          6701: * TeX Mode::    The major modes for editing input to the formatter TeX.
        !          6702: * Outline Mode::The major mode for editing outlines.
        !          6703: * Words::       Moving over and killing words.
        !          6704: * Sentences::   Moving over and killing sentences.
        !          6705: * Paragraphs:: Moving over paragraphs.
        !          6706: * Pages::      Moving over pages.
        !          6707: * Filling::     Filling or justifying text
        !          6708: * Case::        Changing the case of text
        !          6709: @end menu
        !          6710: 
        !          6711: @node Text Mode, Words, Text, Text
        !          6712: @section Text Mode
        !          6713: 
        !          6714: @findex tab-to-tab-stop
        !          6715: @findex edit-tab-stops
        !          6716: @cindex Text mode
        !          6717: @kindex TAB
        !          6718: @findex text-mode
        !          6719:   Editing files of text in a human language ought to be done using Text
        !          6720: mode rather than Lisp or Fundamental mode.  Invoke @kbd{M-x text-mode} to
        !          6721: enter Text mode.  In Text mode, @key{TAB} runs the function
        !          6722: @code{tab-to-tab-stop}, which allows you to use arbitrary tab stops set
        !          6723: with @kbd{M-x edit-tab-stops} (@pxref{Tab Stops}).  Features concerned with
        !          6724: comments in programs are turned off except when explicitly invoked.  The
        !          6725: syntax table is changed so that periods are not considered part of a word,
        !          6726: while apostrophes, backspaces and underlines are.
        !          6727: 
        !          6728: @findex indented-text-mode
        !          6729: @cindex Indented Text mode
        !          6730:   A similar variant mode is Indented Text mode, intended for editing text
        !          6731: in which most lines are indented.  This mode defines @key{TAB} to run
        !          6732: @code{indent-relative} (@pxref{Indentation}), and makes Auto Fill indent
        !          6733: the lines it creates.  The result is that normally a line made by Auto
        !          6734: Filling, or by @key{LFD}, is indented just like the previous line.  Use
        !          6735: @kbd{M-x indented-text-mode} to select this mode.
        !          6736: 
        !          6737: @vindex text-mode-hook
        !          6738:   Entering Text mode or Indented Text mode calls with no arguments the
        !          6739: value of the variable @code{text-mode-hook}, if that value exists and is
        !          6740: not @code{nil}.  This value is also called when modes related to Text mode
        !          6741: are entered; this includes Nroff mode, @TeX{} mode, Outline mode and Mail
        !          6742: mode.  Your hook can look at the value of @code{major-mode} to see which of
        !          6743: these modes is actually being entered.
        !          6744: 
        !          6745: @menu
        !          6746:   Three modes similar to Text mode are of use for editing text that is to
        !          6747: be passed through a text formatter before achieving the form in which
        !          6748: humans are to read it.
        !          6749: 
        !          6750: * Nroff Mode::  The nroff formatter typesets text.
        !          6751: * TeX Mode::    The TeX formatter typesets text and mathematics.
        !          6752: * Texinfo Mode::Texinfo provides both on-line information and printed output
        !          6753:                  from the same source file.
        !          6754: 
        !          6755:   Another similar mode is used for editing outlines.  It allows you
        !          6756: to view the text at various levels of detail.  You can view either
        !          6757: the outline headings alone or both headings and text; you can also
        !          6758: hide some of the headings at lower levels from view to make the high
        !          6759: level structure more visible.
        !          6760: 
        !          6761: * Outline Mode::The major mode for editing outlines.
        !          6762: @end menu
        !          6763: 
        !          6764: @node Nroff Mode, TeX Mode, Text Mode, Text Mode
        !          6765: @subsection Nroff Mode
        !          6766: 
        !          6767: @cindex nroff
        !          6768: @cindex Nroff mode
        !          6769: @findex nroff-mode
        !          6770:   Nroff mode is a mode like Text mode but modified to handle nroff commands
        !          6771: present in the text.  Invoke @kbd{M-x nroff-mode} to enter this mode.  It
        !          6772: differs from Text mode in only a few ways.  All nroff command lines are
        !          6773: considered paragraph separators, so that filling will never garble the
        !          6774: nroff commands.  Pages are separated by @samp{.bp} commands.  Comments
        !          6775: start with backslash-doublequote.  Also, three special commands are
        !          6776: provided that are not in Text mode:
        !          6777: 
        !          6778: @findex forward-text-line
        !          6779: @findex backward-text-line
        !          6780: @findex count-text-lines
        !          6781: @kindex M-n
        !          6782: @kindex M-p
        !          6783: @kindex M-?
        !          6784: @table @kbd
        !          6785: @item M-n
        !          6786: Move to the beginning of the next line that isn't an nroff command
        !          6787: (@code{forward-text-line}).  An argument is a repeat count.
        !          6788: @item M-p
        !          6789: Like @kbd{M-n} but move up (@code{backward-text-line}).
        !          6790: @item M-?
        !          6791: Prints in the echo area the number of text lines (lines that are not
        !          6792: nroff commands) in the region (@code{count-text-lines}).
        !          6793: @end table
        !          6794: 
        !          6795: @cindex Electric Nroff mode
        !          6796: @findex electric-nroff-mode
        !          6797:   The other feature of Nroff mode is Electric Nroff newline mode.  This
        !          6798: is a minor mode that you can turn on or off with @kbd{M-x
        !          6799: electric-nroff-mode} (@pxref{Minor Modes}).  When the mode is on, each
        !          6800: time you use @key{RET} to end a line that contains an nroff command that
        !          6801: opens a kind of grouping, it also inserts the matching nroff command to
        !          6802: close that grouping, on the following line.  For example, if you are at
        !          6803: the beginning of a line and type @kbd{.@: ( b @key{RET}}, this inserts
        !          6804: the matching command @samp{.)b} on a new line following point.
        !          6805: 
        !          6806: @vindex nroff-mode-hook
        !          6807:   Entering Nroff mode calls with no arguments the value of the variable
        !          6808: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
        !          6809: does the same with the variable @code{nroff-mode-hook}.
        !          6810: 
        !          6811: @node TeX Mode, Texinfo Mode, Nroff Mode, Text Mode
        !          6812: @subsection @TeX{} Mode
        !          6813: @cindex TeX
        !          6814: @cindex LaTeX
        !          6815: @cindex TeX mode
        !          6816: @findex TeX-mode
        !          6817: @findex tex-mode
        !          6818: @findex plain-tex-mode
        !          6819: @findex LaTeX-mode
        !          6820: @findex plain-TeX-mode
        !          6821: @findex latex-mode
        !          6822: 
        !          6823:   @TeX{} is a powerful text formatter written by Donald Knuth; it is also
        !          6824: free, like GNU Emacs.  La@TeX{} is a simplified input format for @TeX{},
        !          6825: implemented by @TeX{} macros.  It comes with @TeX{}.@refill
        !          6826: 
        !          6827:   Emacs has a special @TeX{} mode for editing @TeX{} input files.
        !          6828: It provides facilities for checking the balance of delimiters and for
        !          6829: invoking @TeX{} on all or part of the file.
        !          6830: 
        !          6831:   @TeX{} mode has two variants, Plain @TeX{} mode and La@TeX{} mode
        !          6832: (actually two distinct major modes which differ only slightly).  They are
        !          6833: designed for editing the two different input formats.  The command @kbd{M-x
        !          6834: tex-mode} looks at the contents of the buffer to determine whether the
        !          6835: contents appear to be La@TeX{} input or not; it then selects the
        !          6836: appropriate mode.  If it can't tell which is right (e.g., the buffer is
        !          6837: empty), the variable @code{TeX-default-mode} controls which mode is used.
        !          6838: 
        !          6839:   The commands @kbd{M-x plain-tex-mode} and @kbd{M-x latex-mode} explicitly
        !          6840: select the two variants of @TeX{} mode.  Use these commands when @kbd{M-x
        !          6841: tex-mode} does not guess right.@refill
        !          6842: 
        !          6843: @menu
        !          6844: * Editing: TeX Editing.   Special commands for editing in TeX mode.
        !          6845: * Printing: TeX Print.    Commands for printing part of a file with TeX.
        !          6846: @end menu
        !          6847: 
        !          6848: @c !!! Here is information about obtaining TeX.  Update it whenever.
        !          6849: @c     Last updated by RJC on 8 October 1992
        !          6850: @c     based on message from elisabet@@u.washington.edu
        !          6851:   @TeX{} for Unix systems can be obtained from the University of Washington
        !          6852: for a distribution fee.
        !          6853: 
        !          6854:   To order a full distribution, send $200.00 for a 1/2-inch 9-track 1600
        !          6855: bpi (@code{tar} or @code{cpio}) tape reel, or $210.00 for a 1/4-inch
        !          6856: 4-track QIC-24 (@code{tar} or @code{cpio}) cartridge, to:@refill
        !          6857: 
        !          6858: @display
        !          6859: Northwest Computing Support Center
        !          6860: DR-10, Thomson Hall 35
        !          6861: University of Washington
        !          6862: Seattle, Washington 98195
        !          6863: @end display
        !          6864: 
        !          6865: @noindent
        !          6866: Please make checks payable to the University of Washington.@refill
        !          6867: 
        !          6868:   Prepaid orders are preferred but purchase orders are acceptable;
        !          6869: however, purchase orders carry an extra charge of $10.00, to pay for
        !          6870: processing.@refill
        !          6871: 
        !          6872:   Overseas sites: please add to the base cost $20.00 for shipment via 
        !          6873: air parcel post, or $30.00 for shipment via courier.@refill
        !          6874: 
        !          6875:   Please check with the Northwest Computing Support Center at the
        !          6876: University of Washington for current prices and formats:@refill
        !          6877: 
        !          6878: @example
        !          6879: @group
        !          6880: @r{telephone:}  (206) 543-6259
        !          6881: @r{email:}      elisabet@@u.washington.edu
        !          6882: @end group
        !          6883: @end example
        !          6884: 
        !          6885: @node TeX Editing,TeX Print,TeX Mode,TeX Mode
        !          6886: @subsubsection @TeX{} Editing Commands
        !          6887: 
        !          6888:   Here are the special commands provided in @TeX{} mode for editing the
        !          6889: text of the file.
        !          6890: 
        !          6891: @table @kbd
        !          6892: @item "
        !          6893: Insert, according to context, either @samp{@`@`} or @samp{"} or
        !          6894: @samp{@'@'} (@code{TeX-insert-quote}).
        !          6895: @item @key{LFD}
        !          6896: Insert a paragraph break (two newlines) and check the previous
        !          6897: paragraph for unbalanced braces or dollar signs
        !          6898: (@code{TeX-terminate-paragraph}).
        !          6899: @item M-x validate-TeX-buffer
        !          6900: Check each paragraph in the buffer for unbalanced braces or dollar signs.
        !          6901: @c !!! following generates acceptable underfull hbox
        !          6902: @item M-@{
        !          6903: Insert @samp{@{@}} and position point between them (@code{TeX-insert-braces}).
        !          6904: @item M-@}
        !          6905: Move forward past the next unmatched close brace (@code{up-list}).
        !          6906: @item C-c C-f
        !          6907: Close a block for La@TeX{} (@code{TeX-close-LaTeX-block}).
        !          6908: @end table
        !          6909: 
        !          6910: @findex TeX-insert-quote
        !          6911: @kindex " (TeX mode)
        !          6912:   In @TeX{}, the character @samp{"} is not normally used; use @samp{``}
        !          6913: to start a quotation and @samp{''} to end one.  @TeX{} mode defines the key
        !          6914: @kbd{"} to insert @samp{``} after whitespace or an open brace, @samp{"}
        !          6915: after a backslash, or @samp{''} otherwise.  This is done by the command
        !          6916: @code{TeX-insert-quote}.  If you need the character @samp{"} itself in
        !          6917: unusual contexts, use @kbd{C-q} to insert it.  Also, @kbd{"} with a
        !          6918: numeric argument always inserts that number of @samp{"} characters.
        !          6919: 
        !          6920:   In @TeX{} mode, @samp{$} has a special syntax code which attempts to
        !          6921: understand the way @TeX{} math mode delimiters match.  When you insert a
        !          6922: @samp{$} that is meant to exit math mode, the position of the matching
        !          6923: @samp{$} that entered math mode is displayed for a second.  This is the
        !          6924: same feature that displays the open brace that matches a close brace that
        !          6925: is inserted.  However, there is no way to tell whether a @samp{$} enters
        !          6926: math mode or leaves it; so when you insert a @samp{$} that enters math
        !          6927: mode, the previous @samp{$} position is shown as if it were a match, even
        !          6928: though they are actually unrelated.
        !          6929: 
        !          6930: @findex TeX-insert-braces
        !          6931: @kindex M-@{ (TeX mode)
        !          6932: @findex up-list
        !          6933: @kindex M-@} (TeX mode)
        !          6934:   If you prefer to keep braces balanced at all times, you can use @kbd{M-@{}
        !          6935: (@code{TeX-insert-braces}) to insert a pair of braces.  It leaves point
        !          6936: between the two braces so you can insert the text that belongs inside.
        !          6937: Afterward, use the command @kbd{M-@}} (@code{up-list}) to move forward
        !          6938: past the close brace.
        !          6939: 
        !          6940: @findex validate-TeX-buffer
        !          6941: @findex TeX-terminate-paragraph
        !          6942: @kindex LFD (TeX mode)
        !          6943:   There are two commands for checking the matching of braces.  @key{LFD}
        !          6944: (@code{TeX-terminate-paragraph}) checks the paragraph before point, and
        !          6945: inserts two newlines to start a new paragraph.  It prints a message in the
        !          6946: echo area if any mismatch is found.  @kbd{M-x validate-TeX-buffer} checks
        !          6947: the entire buffer, paragraph by paragraph.  When it finds a paragraph that
        !          6948: contains a mismatch, it displays point at the beginning of the paragraph
        !          6949: for a few seconds and pushes a mark at that spot.  Scanning continues
        !          6950: until the whole buffer has been checked or until you type another key.
        !          6951: The positions of the last several paragraphs with mismatches can be
        !          6952: found in the mark ring (@pxref{Mark Ring}).
        !          6953: 
        !          6954:   Note that square brackets and parentheses are matched in @TeX{} mode, not
        !          6955: just braces.  This is wrong for the purpose of checking @TeX{} syntax.
        !          6956: However, parentheses and square brackets are likely to be used in text as
        !          6957: matching delimiters and it is useful for the various motion commands and
        !          6958: automatic match display to work with them.
        !          6959: 
        !          6960: @findex TeX-close-LaTeX-block
        !          6961: @kindex C-c C-f (LaTeX mode)
        !          6962:   In La@TeX{} input, @samp{\begin} and @samp{\end} commands must balance.
        !          6963: After you insert a @samp{\begin}, use @kbd{C-c C-f}
        !          6964: (@code{TeX-close-LaTeX-block}) to insert automatically a matching
        !          6965: @samp{\end} (on a new line following the @samp{\begin}).  A blank line is
        !          6966: inserted between the two, and point is left there.@refill
        !          6967: 
        !          6968: @node TeX Print,,TeX Editing,TeX Mode
        !          6969: @subsubsection @TeX{} Printing Commands
        !          6970: 
        !          6971:   You can invoke @TeX{} as an inferior of Emacs on either the entire
        !          6972: contents of the buffer or just a region at a time.  Running @TeX{} in
        !          6973: this way on just one chapter is a good way to see what your changes
        !          6974: look like without taking the time to format the entire file.
        !          6975: 
        !          6976: @table @kbd
        !          6977: @item C-c C-r
        !          6978: Invoke @TeX{} on the current region, plus the buffer's header
        !          6979: (@code{TeX-region}).
        !          6980: @item C-c C-b
        !          6981: Invoke @TeX{} on the entire current buffer (@code{TeX-buffer}).
        !          6982: @item C-c C-l
        !          6983: Recenter the window showing output from the inferior @TeX{} so that
        !          6984: the last line can be seen (@code{TeX-recenter-output-buffer}).
        !          6985: @item C-c C-k
        !          6986: Kill the inferior @TeX{} (@code{TeX-kill-job}).
        !          6987: @item C-c C-p
        !          6988: Print the output from the last @kbd{C-c C-r} or @kbd{C-c C-b} command
        !          6989: (@code{TeX-print}).
        !          6990: @item C-c C-q
        !          6991: Show the printer queue (@code{TeX-show-print-queue}).
        !          6992: @end table
        !          6993: 
        !          6994: @findex TeX-buffer
        !          6995: @kindex C-c C-b (TeX mode)
        !          6996: @findex TeX-print
        !          6997: @kindex C-c C-p (TeX mode)
        !          6998: @findex TeX-show-print-queue
        !          6999: @kindex C-c C-q (TeX mode)
        !          7000:   You can pass the current buffer through an inferior @TeX{} by means of
        !          7001: @kbd{C-c C-b} (@code{TeX-buffer}).  The formatted output appears in a file
        !          7002: in @file{/tmp}; to print it, type @kbd{C-c C-p} (@code{TeX-print}).
        !          7003: Afterward use @kbd{C-c C-q} (@code{TeX-show-print-queue}) to view the
        !          7004: progress of your output towards being printed.
        !          7005: 
        !          7006: @findex TeX-kill-job
        !          7007: @kindex C-c C-k (TeX mode)
        !          7008: @findex TeX-recenter-output-buffer
        !          7009: @kindex C-c C-l (TeX mode)
        !          7010:   The console output from @TeX{}, including any error messages, appears in a
        !          7011: buffer called @samp{*TeX-shell*}.  If @TeX{} gets an error, you can switch
        !          7012: to this buffer and feed it input (this works as in Shell mode;
        !          7013: @pxref{Interactive Shell}).  Without switching to this buffer you can scroll
        !          7014: it so that its last line is visible by typing @kbd{C-c C-l}.
        !          7015: 
        !          7016:   Type @kbd{C-c C-k} (@code{TeX-kill-job}) to kill the @TeX{} process if
        !          7017: you see that its output is no longer useful.  Using @kbd{C-c C-b} or
        !          7018: @kbd{C-c C-r} also kills any @TeX{} process still running.@refill
        !          7019: 
        !          7020: @findex TeX-region
        !          7021: @kindex C-c C-r (TeX mode)
        !          7022:   You can also pass an arbitrary region through an inferior @TeX{} by typing
        !          7023: @kbd{C-c C-r} (@code{TeX-region}).  This is tricky, however, because most files
        !          7024: of @TeX{} input contain commands at the beginning to set parameters and
        !          7025: define macros, without which no later part of the file will format
        !          7026: correctly.  To solve this problem, @kbd{C-c C-r} allows you to designate a
        !          7027: part of the file as containing essential commands; it is included before
        !          7028: the specified region as part of the input to @TeX{}.  The designated part
        !          7029: of the file is called the @dfn{header}.
        !          7030: 
        !          7031: @cindex header (TeX mode)
        !          7032:   To indicate the bounds of the header in Plain @TeX{} mode, you insert two
        !          7033: special strings in the file.  Insert @samp{%**start of header} before the
        !          7034: header, and @samp{%**end of header} after it.  Each string must appear
        !          7035: entirely on one line, but there may be other text on the line before or
        !          7036: after.  The lines containing the two strings are included in the header.
        !          7037: If @samp{%**start of header} does not appear within the first 100 lines of
        !          7038: the buffer, @kbd{C-c C-r} assumes that there is no header.
        !          7039: 
        !          7040:   In La@TeX{} mode, the header begins with @samp{\documentstyle} and ends
        !          7041: with @samp{\begin@{document@}}.  These are commands that La@TeX{} requires
        !          7042: you to use in any case, so nothing special needs to be done to identify the
        !          7043: header.
        !          7044: 
        !          7045: @vindex TeX-mode-hook
        !          7046: @vindex LaTeX-mode-hook
        !          7047: @vindex plain-TeX-mode-hook
        !          7048:   Entering either kind of @TeX{} mode calls with no arguments the value of
        !          7049: the variable @code{text-mode-hook}, if that value exists and is not
        !          7050: @code{nil}; then it does the same with the variable @code{TeX-mode-hook}.
        !          7051: Finally it does the same with either @code{plain-TeX-mode-hook} or
        !          7052: @code{LaTeX-mode-hook}.
        !          7053: 
        !          7054: @node Texinfo Mode, Outline Mode, TeX Mode, Text Mode
        !          7055: @subsection Texinfo Mode
        !          7056: @cindex Texinfo mode
        !          7057: @findex texinfo-mode
        !          7058: 
        !          7059: Texinfo is a documentation system that uses a single source file to
        !          7060: produce both on-line information and printed output.  This means that
        !          7061: instead of writing two different documents, one for the on-line help or
        !          7062: other on-line information and the other for a typeset manual or other
        !          7063: printed work, you need write only one document.  When the work is
        !          7064: revised, you need revise only one document.  (You can read the on-line
        !          7065: information, known as an @dfn{Info file}, with an Info
        !          7066: documentation-reading program.  @inforef{Top, info, info}, for more
        !          7067: information about Info.)  Texinfo is the format in which documentation
        !          7068: for GNU utilities and libraries is written.
        !          7069: 
        !          7070: Texinfo mode provides special features for working with Texinfo files
        !          7071: including utilities to construct Info menus and pointers automatically,
        !          7072: keybindings to insert frequently used formatting commands, and
        !          7073: keybindings for commands to format both for Info and for printing.
        !          7074: 
        !          7075: Texinfo mode is described in @ref{Texinfo Mode, , Using Texinfo Mode,
        !          7076: texinfo, Texinfo; The GNU Documentation Format}.
        !          7077: 
        !          7078: @node Outline Mode,, Texinfo Mode, Text Mode
        !          7079: @subsection Outline Mode
        !          7080: @cindex Outline mode
        !          7081: @cindex outlines
        !          7082: @cindex selective display
        !          7083: @cindex invisible lines
        !          7084: 
        !          7085: @findex outline-mode
        !          7086:   Outline mode is a major mode much like Text mode but intended for editing
        !          7087: outlines.  It allows you to make parts of the text temporarily invisible
        !          7088: so that you can see just the overall structure of the outline.  Type
        !          7089: @kbd{M-x outline-mode} to turn on Outline mode in the current buffer.
        !          7090: 
        !          7091: @vindex outline-mode-hook
        !          7092:   Entering Outline mode calls with no arguments the value of the variable
        !          7093: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
        !          7094: does the same with the variable @code{outline-mode-hook}.
        !          7095: 
        !          7096:   When a line is invisible in outline mode, it does not appear on the
        !          7097: screen.  The screen appears exactly as if the invisible line
        !          7098: were deleted, except that an ellipsis (three periods in a row) appears
        !          7099: at the end of the previous visible line (only one ellipsis no matter
        !          7100: how many invisible lines follow).
        !          7101: 
        !          7102:   All editing commands treat the text of the invisible line as part of the
        !          7103: previous visible line.  For example, @kbd{C-n} moves onto the next visible
        !          7104: line.  Killing an entire visible line, including its terminating newline,
        !          7105: really kills all the following invisible lines along with it; yanking it
        !          7106: all back yanks the invisible lines and they remain invisible.
        !          7107: 
        !          7108: @menu
        !          7109: * Format: Outline Format.        What the text of an outline looks like.
        !          7110: * Motion: Outline Motion.        Special commands for moving through outlines.
        !          7111: * Visibility: Outline Visibility. Commands to control what is visible.
        !          7112: @end menu
        !          7113: 
        !          7114: @node Outline Format,Outline Motion,Outline Mode, Outline Mode
        !          7115: @subsubsection Format of Outlines
        !          7116: 
        !          7117: @cindex heading lines (Outline mode)
        !          7118: @cindex body lines (Outline mode)
        !          7119:   Outline mode assumes that the lines in the buffer are of two types:
        !          7120: @dfn{heading lines} and @dfn{body lines}.  A heading line represents a topic in the
        !          7121: outline.  Heading lines start with one or more stars; the number of stars
        !          7122: determines the depth of the heading in the outline structure.  Thus, a
        !          7123: heading line with one star is a major topic; all the heading lines with
        !          7124: two stars between it and the next one-star heading are its subtopics; and
        !          7125: so on.  Any line that is not a heading line is a body line.  Body lines
        !          7126: belong to the preceding heading line.  Here is an example:
        !          7127: 
        !          7128: @example
        !          7129: * Food
        !          7130: 
        !          7131: This is the body,
        !          7132: which says something about the topic of food.
        !          7133: 
        !          7134: ** Delicious Food
        !          7135: 
        !          7136: This is the body of the second-level header.
        !          7137: 
        !          7138: ** Distasteful Food
        !          7139: 
        !          7140: This could have
        !          7141: a body too, with
        !          7142: several lines.
        !          7143: 
        !          7144: *** Dormitory Food
        !          7145: 
        !          7146: * Shelter
        !          7147: 
        !          7148: A second first-level topic with its header line.
        !          7149: @end example
        !          7150: 
        !          7151:   A heading line together with all following body lines is called
        !          7152: collectively an @dfn{entry}.  A heading line together with all following
        !          7153: deeper heading lines and their body lines is called a @dfn{subtree}.
        !          7154: 
        !          7155: @vindex outline-regexp
        !          7156:   You can customize the criterion for distinguishing heading lines
        !          7157: by setting the variable @code{outline-regexp}.  Any line whose
        !          7158: beginning has a match for this regexp is considered a heading line.
        !          7159: Matches that start within a line (not at the beginning) do not count.
        !          7160: The length of the matching text determines the level of the heading;
        !          7161: longer matches make a more deeply nested level.  Thus, for example,
        !          7162: if a text formatter has commands @samp{@@chapter}, @samp{@@section}
        !          7163: and @samp{@@subsection} to divide the document into chapters and
        !          7164: sections, you could make those lines count as heading lines by
        !          7165: setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}.
        !          7166: Note the trick: the two words @samp{chapter} and @samp{section} are equally
        !          7167: long, but by defining the regexp to match only @samp{chap} we ensure
        !          7168: that the length of the text matched on a chapter heading is shorter,
        !          7169: so that Outline mode will know that sections are contained in chapters.
        !          7170: This works as long as no other command starts with @samp{@@chap}.
        !          7171: 
        !          7172:   Outline mode makes a line invisible by changing the newline before it
        !          7173: into an @sc{ascii} Control-M (code 015).  Most editing commands that work on
        !          7174: lines treat an invisible line as part of the previous line because,
        !          7175: strictly speaking, it @i{is} part of that line, since there is no longer a
        !          7176: newline in between.  When you save the file in Outline mode, Control-M
        !          7177: characters are saved as newlines, so the invisible lines become ordinary
        !          7178: lines in the file.  But saving does not change the visibility status of a
        !          7179: line inside Emacs.
        !          7180: 
        !          7181: @node Outline Motion,Outline Visibility,Outline Format,Outline Mode
        !          7182: @subsubsection Outline Motion Commands
        !          7183: 
        !          7184:   There are some special motion commands in Outline mode that move
        !          7185: backward and forward to heading lines.
        !          7186: 
        !          7187: @table @kbd
        !          7188: @item C-c C-n
        !          7189: Move point to the next visible heading line
        !          7190: (@code{outline-next-visible-heading}).
        !          7191: @c !!! following generates acceptable underfull hbox
        !          7192: @item C-c C-p
        !          7193: Move point to the previous visible heading line
        !          7194: (@code{outline-previous-visible-heading}).
        !          7195: @item C-c C-f
        !          7196: Move point to the next visible heading line at the same level
        !          7197: as the one point is on (@code{outline-forward-same-level}).
        !          7198: @item C-c C-b
        !          7199: Move point to the previous visible heading line at the same level
        !          7200: (@code{outline-backward-same-level}).
        !          7201: @item C-c C-u
        !          7202: Move point up to a lower-level (more inclusive) visible heading line
        !          7203: (@code{outline-up-heading}).
        !          7204: @end table
        !          7205: 
        !          7206: @findex outline-next-visible-heading
        !          7207: @findex outline-previous-visible-heading
        !          7208: @kindex C-c C-n (Outline mode)
        !          7209: @kindex C-c C-p (Outline mode)
        !          7210:   @kbd{C-c C-n} (@code{next-visible-heading}) moves down to the next
        !          7211: heading line.  @kbd{C-c C-p} (@code{previous-visible-heading}) moves
        !          7212: similarly backward.  Both accept numeric arguments as repeat counts.  The
        !          7213: names emphasize that invisible headings are skipped, but this is not really
        !          7214: a special feature.  All editing commands that look for lines ignore the
        !          7215: invisible lines automatically.@refill
        !          7216: 
        !          7217: @findex outline-up-heading
        !          7218: @findex outline-forward-same-level
        !          7219: @findex outline-backward-same-level
        !          7220: @kindex C-c C-f (Outline mode)
        !          7221: @kindex C-c C-b (Outline mode)
        !          7222: @kindex C-c C-u (Outline mode)
        !          7223: @c !!! written verbosely to prevent overfull hbox
        !          7224:   More advanced motion commands understand the levels of headings.
        !          7225: The two commands, @kbd{C-c C-f} (@code{outline-forward-same-level}) and
        !          7226: @kbd{C-c C-b} (@code{outline-backward-same-level}), move from one
        !          7227: heading line to another visible heading at the same depth in
        !          7228: the outline.  @kbd{C-c C-u} (@code{outline-up-heading}) moves
        !          7229: backward to another heading that is less deeply nested.
        !          7230: 
        !          7231: @node Outline Visibility,,Outline Motion,Outline Mode
        !          7232: @subsubsection Outline Visibility Commands
        !          7233: 
        !          7234:   The other special commands of outline mode are used to make lines visible
        !          7235: or invisible.  Their names all start with @code{hide} or @code{show}.
        !          7236: Most of them fall into pairs of opposites.  They are not undoable; instead,
        !          7237: you can undo right past them.  Making lines visible or invisible is simply
        !          7238: not recorded by the undo mechanism.
        !          7239: 
        !          7240: @table @kbd
        !          7241: @item M-x hide-body
        !          7242: Make all body lines in the buffer invisible.
        !          7243: @item M-x show-all
        !          7244: Make all lines in the buffer visible.
        !          7245: @item C-c C-h
        !          7246: Make everything under this heading invisible, not including this
        !          7247: heading itself (@code{hide-subtree}).
        !          7248: @item C-c C-s
        !          7249: Make everything under this heading visible, including body,
        !          7250: subheadings, and their bodies (@code{show-subtree}).
        !          7251: @item M-x hide-leaves
        !          7252: Make the body of this heading line, and of all its subheadings,
        !          7253: invisible.
        !          7254: @item M-x show-branches
        !          7255: Make all subheadings of this heading line, at all levels, visible.
        !          7256: @item C-c C-i
        !          7257: Make immediate subheadings (one level down) of this heading line
        !          7258: visible (@code{show-children}).
        !          7259: @item M-x hide-entry
        !          7260: Make this heading line's body invisible.
        !          7261: @item M-x show-entry
        !          7262: Make this heading line's body visible.
        !          7263: @end table
        !          7264: 
        !          7265: @findex hide-entry
        !          7266: @findex show-entry
        !          7267:   Two commands that are exact opposites are @kbd{M-x hide-entry} and
        !          7268: @kbd{M-x show-entry}.  They are used with point on a heading line, and
        !          7269: apply only to the body lines of that heading.  The subtopics and their
        !          7270: bodies are not affected.
        !          7271: 
        !          7272: @findex hide-subtree
        !          7273: @findex show-subtree
        !          7274: @kindex C-c C-s (Outline mode)
        !          7275: @kindex C-c C-h (Outline mode)
        !          7276: @cindex subtree (Outline mode)
        !          7277:   Two more powerful opposites are @kbd{C-c C-h} (@code{hide-subtree}) and
        !          7278: @kbd{C-c C-s} (@code{show-subtree}).  Both expect to be used when point is
        !          7279: on a heading line, and both apply to all the lines of that heading's
        !          7280: @dfn{subtree}: its body, all its subheadings, both direct and indirect, and
        !          7281: all of their bodies.  In other words, the subtree contains everything
        !          7282: following this heading line, up to and not including the next heading of
        !          7283: the same or higher rank.@refill
        !          7284: 
        !          7285: @findex hide-leaves
        !          7286: @findex show-branches
        !          7287:   Intermediate between a visible subtree and an invisible one is having
        !          7288: all the subheadings visible but none of the body.  There are two commands
        !          7289: for doing this, depending on whether you want to hide the bodies or
        !          7290: make the subheadings visible.  They are @kbd{M-x hide-leaves} and
        !          7291: @kbd{M-x show-branches}.
        !          7292: 
        !          7293: @kindex C-c C-i (Outline mode)
        !          7294: @findex show-children
        !          7295:   A little weaker than @code{show-branches} is @kbd{C-c C-i}
        !          7296: (@code{show-children}).  It makes just the direct subheadings
        !          7297: visible---those one level down.  Deeper subheadings remain invisible, if
        !          7298: they were invisible.@refill
        !          7299: 
        !          7300: @findex hide-body
        !          7301: @findex show-all
        !          7302:   Two commands have a blanket effect on the whole file.  @kbd{M-x hide-body}
        !          7303: makes all body lines invisible, so that you see just the outline structure.
        !          7304: @kbd{M-x show-all} makes all lines visible.  These commands can be thought
        !          7305: of as a pair of opposites even though @kbd{M-x show-all} applies to more
        !          7306: than just body lines.
        !          7307: 
        !          7308: @vindex selective-display-ellipses
        !          7309:   The use of ellipses at the ends of visible lines can be turned off
        !          7310: by setting @code{selective-display-ellipses} to @code{nil}.  Then there
        !          7311: is no visible indication of the presence of invisible lines.
        !          7312: 
        !          7313: @node Words, Sentences, Text Mode, Text
        !          7314: @section Words
        !          7315: @cindex words
        !          7316: @cindex Meta
        !          7317: 
        !          7318:   Emacs has commands for moving over or operating on words.  By convention,
        !          7319: the keys for them are all @kbd{Meta-} characters.
        !          7320: 
        !          7321: @c widecommands
        !          7322: @table @kbd
        !          7323: @item M-f
        !          7324: Move forward over a word (@code{forward-word}).
        !          7325: @item M-b
        !          7326: Move backward over a word (@code{backward-word}).
        !          7327: @item M-d
        !          7328: Kill up to the end of a word (@code{kill-word}).
        !          7329: @item M-@key{DEL}
        !          7330: Kill back to the beginning of a word (@code{backward-kill-word}).
        !          7331: @item M-@@
        !          7332: Mark the end of the next word (@code{mark-word}).
        !          7333: @item M-t
        !          7334: Transpose two words;  drag a word forward
        !          7335: or backward across other words (@code{transpose-words}).
        !          7336: @end table
        !          7337: 
        !          7338:   Notice how these keys form a series that parallels the
        !          7339: character-based @kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @kbd{C-t} and
        !          7340: @key{DEL}.  @kbd{M-@@} is related to @kbd{C-@@}, which is an alias for
        !          7341: @kbd{C-@key{SPC}}.@refill
        !          7342: 
        !          7343: @kindex M-f
        !          7344: @kindex M-b
        !          7345: @findex forward-word
        !          7346: @findex backward-word
        !          7347:   The commands @kbd{Meta-f} (@code{forward-word}) and @kbd{Meta-b}
        !          7348: (@code{backward-word}) move forward and backward over words.  They are thus
        !          7349: analogous to @kbd{Control-f} and @kbd{Control-b}, which move over single
        !          7350: characters.  Like their @kbd{Control-} analogues, @kbd{Meta-f} and
        !          7351: @kbd{Meta-b} move several words if given an argument.  @kbd{Meta-f} with a
        !          7352: negative argument moves backward, and @kbd{Meta-b} with a negative argument
        !          7353: moves forward.  Forward motion stops right after the last letter of the
        !          7354: word, while backward motion stops right before the first letter.@refill
        !          7355: 
        !          7356: @kindex M-d
        !          7357: @findex kill-word
        !          7358:   @kbd{Meta-d} (@code{kill-word}) kills the word after point.  To be
        !          7359: precise, it kills everything from point to the place @kbd{Meta-f} would
        !          7360: move to.  Thus, if point is in the middle of a word, @kbd{Meta-d} kills
        !          7361: just the part after point.  If some punctuation comes between point and the
        !          7362: next word, it is killed along with the word.  (If you wish to kill only the
        !          7363: next word but not the punctuation before it, simply do @kbd{Meta-f} to get
        !          7364: the end, and kill the word backwards with @kbd{Meta-@key{DEL}}.)
        !          7365: @kbd{Meta-d} takes arguments just like @kbd{Meta-f}.
        !          7366: 
        !          7367: @findex backward-kill-word
        !          7368: @kindex M-DEL
        !          7369:   @kbd{Meta-@key{DEL}} (@code{backward-kill-word}) kills the word before
        !          7370: point.  It kills everything from point back to where @kbd{Meta-b} would
        !          7371: move to.  If point is after the space in @w{@samp{FOO, BAR}}, then
        !          7372: @w{@samp{FOO, }} is killed.  (If you wish to kill just @samp{FOO}, do
        !          7373: @kbd{Meta-b Meta-d} instead of @kbd{Meta-@key{DEL}}.)
        !          7374: 
        !          7375: @cindex transposition
        !          7376: @kindex M-t
        !          7377: @findex transpose-words
        !          7378:   @kbd{Meta-t} (@code{transpose-words}) exchanges the word before or
        !          7379: containing point with the following word.  The delimiter characters between
        !          7380: the words do not move.  For example, @w{@samp{FOO, BAR}} transposes into
        !          7381: @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}.  @xref{Transpose}, for
        !          7382: more on transposition and on arguments to transposition commands.
        !          7383: 
        !          7384: @kindex M-@@
        !          7385: @findex mark-word
        !          7386:   To operate on the next @var{n} words with an operation which applies
        !          7387: between point and mark, you can either set the mark at point and then move
        !          7388: over the words, or you can use the command @kbd{Meta-@@} (@code{mark-word})
        !          7389: which does not move point, but sets the mark where @kbd{Meta-f} would move
        !          7390: to.  It can be given arguments just like @kbd{Meta-f}.
        !          7391: 
        !          7392: @cindex syntax table
        !          7393:   The word commands' understanding of syntax is completely controlled by
        !          7394: the syntax table.  Any character can, for example, be declared to be a word
        !          7395: delimiter.  @xref{Syntax}.
        !          7396: 
        !          7397: @node Sentences, Paragraphs, Words, Text
        !          7398: @section Sentences
        !          7399: @cindex sentences
        !          7400: 
        !          7401:   The Emacs commands for manipulating sentences and paragraphs are mostly
        !          7402: on @kbd{Meta-} keys, so as to be like the word-handling commands.
        !          7403: 
        !          7404: @table @kbd
        !          7405: @item M-a
        !          7406: @c !!! added @* to prevent overfull hbox
        !          7407: Move back to the beginning of the sentence@*
        !          7408: (@code{backward-sentence}).
        !          7409: @item M-e
        !          7410: Move forward to the end of the sentence (@code{forward-sentence}).
        !          7411: @item M-k
        !          7412: Kill forward to the end of the sentence (@code{kill-sentence}).
        !          7413: @item C-x @key{DEL}
        !          7414: Kill back to the beginning of the sentence (@code{backward-kill-sentence}).
        !          7415: @end table
        !          7416: 
        !          7417: @kindex M-a
        !          7418: @kindex M-e
        !          7419: @findex backward-sentence
        !          7420: @findex forward-sentence
        !          7421:   The commands @kbd{Meta-a} and @kbd{Meta-e} (@code{backward-sentence} and
        !          7422: @code{forward-sentence}) move to the beginning and end of the current
        !          7423: sentence, respectively.  They were chosen to resemble @kbd{Control-a} and
        !          7424: @kbd{Control-e}, which move to the beginning and end of a line.  Unlike
        !          7425: them, @kbd{Meta-a} and @w{@kbd{Meta-e}} if repeated or given numeric arguments
        !          7426: move over successive sentences.  Emacs assumes that the typist's convention
        !          7427: is followed, and thus considers a sentence to end wherever there is a
        !          7428: @samp{.}, @samp{?} or @samp{!} followed by the end of a line or two spaces,
        !          7429: with any number of @samp{)}, @samp{]}, @samp{'}, or @samp{"} characters
        !          7430: allowed in between.  A sentence also begins or ends wherever a paragraph
        !          7431: begins or ends.
        !          7432: 
        !          7433:   Neither @kbd{M-a} nor @kbd{M-e} moves past the newline or spaces beyond
        !          7434: the sentence edge at which it is stopping.
        !          7435: 
        !          7436: @kindex M-k
        !          7437: @kindex C-x DEL
        !          7438: @findex kill-sentence
        !          7439: @findex backward-kill-sentence
        !          7440:   Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go
        !          7441: with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command
        !          7442: @kbd{M-k} (@code{kill-sentence}) which kills from point to the end of the
        !          7443: sentence.  With minus one as an argument it kills back to the beginning of
        !          7444: the sentence.  Larger arguments serve as a repeat count.@refill
        !          7445: 
        !          7446:   There is a special command, @kbd{C-x @key{DEL}}
        !          7447: (@code{backward-kill-sentence}) for killing back to the beginning of a
        !          7448: sentence, because this is useful when you change your mind in the middle of
        !          7449: composing text.@refill
        !          7450: 
        !          7451: @vindex sentence-end
        !          7452:   The variable @code{sentence-end} controls recognition of the end of a
        !          7453: sentence.  It is a regexp that matches the last few characters of a
        !          7454: sentence, together with the whitespace following the sentence.  Its
        !          7455: normal value is
        !          7456: 
        !          7457: @example
        !          7458: "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
        !          7459: @end example
        !          7460: 
        !          7461: @noindent
        !          7462: This example is explained in the section on regexps.  @xref{Regexps}.
        !          7463: 
        !          7464: @node Paragraphs, Pages, Sentences, Text
        !          7465: @section Paragraphs
        !          7466: @cindex paragraphs
        !          7467: @kindex M-[
        !          7468: @kindex M-]
        !          7469: @findex backward-paragraph
        !          7470: @findex forward-paragraph
        !          7471: 
        !          7472:   The Emacs commands for manipulating paragraphs are also @kbd{Meta-}
        !          7473: keys.
        !          7474: 
        !          7475: @table @kbd
        !          7476: @item M-[
        !          7477: @c !!! added @* to prevent overfull hbox
        !          7478: Move back to previous paragraph beginning@*
        !          7479: (@code{backward-paragraph}).
        !          7480: @item M-]
        !          7481: Move forward to next paragraph end (@code{forward-paragraph}).
        !          7482: @item M-h
        !          7483: Put point and mark around this or next paragraph (@code{mark-paragraph}).
        !          7484: @end table
        !          7485: 
        !          7486:   @kbd{Meta-[} moves to the beginning of the current or previous paragraph,
        !          7487: while @kbd{Meta-]} moves to the end of the current or next paragraph.
        !          7488: Blank lines and text formatter command lines separate paragraphs and are
        !          7489: not part of any paragraph.  Also, an indented line starts a new
        !          7490: paragraph.
        !          7491: 
        !          7492:   In major modes for programs (as opposed to Text mode), paragraphs begin
        !          7493: and end only at blank lines.  This makes the paragraph commands continue to
        !          7494: be useful even though there are no paragraphs per se.
        !          7495: 
        !          7496:   When there is a fill prefix, then paragraphs are delimited by all lines
        !          7497: which don't start with the fill prefix.  @xref{Filling}.
        !          7498: 
        !          7499: @kindex M-h
        !          7500: @findex mark-paragraph
        !          7501:   When you wish to operate on a paragraph, you can use the command
        !          7502: @kbd{Meta-h} (@code{mark-paragraph}) to set the region around it.  This
        !          7503: command puts point at the beginning and mark at the end of the paragraph
        !          7504: point was in.  If point is between paragraphs (in a run of blank lines, or
        !          7505: at a boundary), the paragraph following point is surrounded by point and
        !          7506: mark.  If there are blank lines preceding the first line of the paragraph,
        !          7507: one of these blank lines is included in the region.  Thus, for example,
        !          7508: @kbd{M-h C-w} kills the paragraph around or after point.
        !          7509: 
        !          7510: @vindex paragraph-start
        !          7511: @vindex paragraph-separate
        !          7512: @c !!! Written verbosely to avoid overfull hbox
        !          7513:   The precise definition of a paragraph boundary is controlled by the
        !          7514: two variables @code{paragraph-separate} and @code{paragraph-start}.  The value
        !          7515: of @code{paragraph-start} is a regexp that should match any line that
        !          7516: either starts or separates paragraphs.  The value of
        !          7517: @code{paragraph-separate} is another regexp that should match only lines
        !          7518: that separate paragraphs without being part of any paragraph.  Lines that
        !          7519: start a new paragraph and are contained in it must match both regexps.  For
        !          7520: example, normally @code{paragraph-start} is @w{@code{"^[ @t{\}t@t{\}n@t{\}f]"}}
        !          7521: and @code{paragraph-separate} is @w{@code{"^[ @t{\}t@t{\}f]*$"}}.
        !          7522: 
        !          7523:   Normally it is desirable for page boundaries to separate paragraphs.
        !          7524: The default values of these variables recognize the usual separator for
        !          7525: pages.
        !          7526: 
        !          7527: @node Pages, Filling, Paragraphs, Text
        !          7528: @section Pages
        !          7529: 
        !          7530: @cindex pages
        !          7531: @cindex formfeed
        !          7532:   Files are often thought of as divided into @dfn{pages} by the
        !          7533: @dfn{formfeed} character (@sc{ascii} Control-L, octal code 014).  For example,
        !          7534: if a file is printed on a line printer, each page of the file, in this
        !          7535: sense, will start on a new page of paper.  Emacs treats a page-separator
        !          7536: character just like any other character.  It can be inserted with @kbd{C-q
        !          7537: C-l}, or deleted with @key{DEL}.  Thus, you are free to paginate your file
        !          7538: or not.  However, since pages are often meaningful divisions of the file,
        !          7539: commands are provided to move over them and operate on them.
        !          7540: 
        !          7541: @c WideCommands
        !          7542: @table @kbd
        !          7543: @item C-x [
        !          7544: Move point to previous page boundary (@code{backward-page}).
        !          7545: @item C-x ]
        !          7546: Move point to next page boundary (@code{forward-page}).
        !          7547: @item C-x C-p
        !          7548: Put point and mark around this page (or another page) (@code{mark-page}).
        !          7549: @item C-x l
        !          7550: Count the lines in this page (@code{count-lines-page}).
        !          7551: @end table
        !          7552: 
        !          7553: @kindex C-x [
        !          7554: @kindex C-x ]
        !          7555: @findex forward-page
        !          7556: @findex backward-page
        !          7557:   The @kbd{C-x [} (@code{backward-page}) command moves point to immediately
        !          7558: after the previous page delimiter.  If point is already right after a page
        !          7559: delimiter, it skips that one and stops at the previous one.  A numeric
        !          7560: argument serves as a repeat count.  The @kbd{C-x ]} (@code{forward-page})
        !          7561: command moves forward past the next page delimiter.
        !          7562: 
        !          7563: @kindex C-x C-p
        !          7564: @findex mark-page
        !          7565:   The @kbd{C-x C-p} command (@code{mark-page}) puts point at the beginning
        !          7566: of the current page and the mark at the end.  The page delimiter at the end
        !          7567: is included (the mark follows it).  The page delimiter at the front is
        !          7568: excluded (point follows it).  This command can be followed by @kbd{C-w} to
        !          7569: kill a page which is to be moved elsewhere.  If it is inserted after a page
        !          7570: delimiter, at a place where @kbd{C-x ]} or @kbd{C-x [} would take you, then
        !          7571: the page will be properly delimited before and after once again.
        !          7572: 
        !          7573:   A numeric argument to @kbd{C-x C-p} is used to specify which page to go
        !          7574: to, relative to the current one.  Zero means the current page.  One means
        !          7575: the next page, and @minus{}1 means the previous one.
        !          7576: 
        !          7577: @kindex C-x l
        !          7578: @findex count-lines-page
        !          7579:   The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding
        !          7580: where to break a page in two.  It prints in the echo area the total number
        !          7581: of lines in the current page, and then divides it up into those preceding
        !          7582: the current line and those following, as in
        !          7583: 
        !          7584: @example
        !          7585: Page has 96 (72+25) lines
        !          7586: @end example
        !          7587: 
        !          7588: @noindent
        !          7589:   Notice that the sum is off by one; this is correct if point is not at the
        !          7590: beginning of a line.
        !          7591: 
        !          7592: @vindex page-delimiter
        !          7593:   The variable @code{page-delimiter} should have as its value a regexp that
        !          7594: matches the beginning of a line that separates pages.  This is what defines
        !          7595: where pages begin.  The normal value of this variable is @code{"^@t{\}f"},
        !          7596: which matches a formfeed character at the beginning of a line.
        !          7597: 
        !          7598: @node Filling, Case, Pages, Text
        !          7599: @section Filling Text
        !          7600: @cindex filling
        !          7601: @cindex wrapping
        !          7602: 
        !          7603:   With Auto Fill mode, text can be @dfn{filled} (broken up into lines
        !          7604: that fit in a specified width) as you insert it.  If you alter existing
        !          7605: text it may no longer be properly filled; then explicit commands for
        !          7606: filling can be used.  (Filling is sometimes called ``wrapping'' in the
        !          7607: terminology used for other text editors, but we don't use that term,
        !          7608: because it could just as well refer to the continuation of long lines
        !          7609: which happens in Emacs if you @emph{don't} fill them.)
        !          7610: 
        !          7611: @menu
        !          7612: * Auto Fill::    Auto Fill mode breaks long lines automatically.
        !          7613: * Fill Commands:: Commands to refill paragraphs and center lines.
        !          7614: * Fill Prefix::   Filling when every line is indented or in a comment, etc.
        !          7615: @end menu
        !          7616: 
        !          7617: @node Auto Fill, Fill Commands, Filling, Filling
        !          7618: @subsection Auto Fill Mode
        !          7619: @cindex Auto Fill mode
        !          7620: 
        !          7621:   @dfn{Auto Fill} mode is a minor mode in which lines are broken
        !          7622: automatically when they become too wide.  Breaking happens only when
        !          7623: you type a @key{SPC} or @key{RET}.
        !          7624: 
        !          7625: @table @kbd
        !          7626: @item M-x auto-fill-mode
        !          7627: Enable or disable Auto Fill mode.
        !          7628: @item @key{SPC}
        !          7629: @itemx @key{RET}
        !          7630: In Auto Fill mode, break lines when appropriate.
        !          7631: @end table
        !          7632: 
        !          7633: @findex auto-fill-mode
        !          7634:   @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off if
        !          7635: it was on.  With a positive numeric argument it always turns Auto Fill mode
        !          7636: on, and with a negative argument always turns it off.  You can see when
        !          7637: Auto Fill mode is in effect by the presence of the word @samp{Fill} in the
        !          7638: mode line, inside the parentheses.  Auto Fill mode is a minor mode, turned
        !          7639: on or off for each buffer individually.  @xref{Minor Modes}.
        !          7640: 
        !          7641:   In Auto Fill mode, lines are broken automatically at spaces when they get
        !          7642: longer than the desired width.  Line breaking and rearrangement takes place
        !          7643: only when you type @key{SPC} or @key{RET}.  If you wish to insert a space
        !          7644: or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} or
        !          7645: @kbd{C-q @key{LFD}} (recall that a newline is really a linefeed).  Also,
        !          7646: @kbd{C-o} inserts a newline without line breaking.
        !          7647: 
        !          7648:   Auto Fill mode works well with Lisp mode, because when it makes a new
        !          7649: line in Lisp mode it indents that line with @key{TAB}.  If a line ending in
        !          7650: a comment gets too long, the text of the comment is split into two
        !          7651: comment lines.  Optionally new comment delimiters are inserted at the end of
        !          7652: the first line and the beginning of the second so that each line is
        !          7653: a separate comment; the variable @code{comment-multi-line} controls the
        !          7654: choice (@pxref{Comments}).
        !          7655: 
        !          7656:   Auto Fill mode does not refill entire paragraphs.  It can break lines but
        !          7657: cannot merge lines.  So editing in the middle of a paragraph can result in
        !          7658: a paragraph that is not correctly filled.  The easiest way to make the
        !          7659: paragraph properly filled again is usually with the explicit fill commands.
        !          7660: 
        !          7661:   Many users like Auto Fill mode and want to use it in all text files.
        !          7662: The section on init files says how to arrange this permanently for yourself.
        !          7663: @xref{Init File}.
        !          7664: 
        !          7665: @node Fill Commands, Fill Prefix, Auto Fill, Filling
        !          7666: @subsection Explicit Fill Commands
        !          7667: 
        !          7668: @table @kbd
        !          7669: @item M-q
        !          7670: Fill current paragraph (@code{fill-paragraph}).
        !          7671: @item M-g
        !          7672: Fill each paragraph in the region (@code{fill-region}).
        !          7673: @item C-x f
        !          7674: Set the fill column (@code{set-fill-column}).
        !          7675: @item M-x fill-region-as-paragraph.
        !          7676: Fill the region, considering it as one paragraph.
        !          7677: @item M-s
        !          7678: Center a line.
        !          7679: @end table
        !          7680: 
        !          7681: @kindex M-q
        !          7682: @findex fill-paragraph
        !          7683:   To refill a paragraph, use the command @kbd{Meta-q}
        !          7684: (@code{fill-paragraph}).  It causes the paragraph that point is inside, or
        !          7685: the one after point if point is between paragraphs, to be refilled.  All
        !          7686: the line-breaks are removed, and then new ones are inserted where
        !          7687: necessary.  @kbd{M-q} can be undone with @kbd{C-_}.  @xref{Undo}.@refill
        !          7688: 
        !          7689: @kindex M-g
        !          7690: @findex fill-region
        !          7691:   To refill many paragraphs, use @kbd{M-g} (@code{fill-region}), which
        !          7692: divides the region into paragraphs and fills each of them.
        !          7693: 
        !          7694: @findex fill-region-as-paragraph
        !          7695:   @kbd{Meta-q} and @kbd{Meta-g} use the same criteria as @kbd{Meta-h}
        !          7696: for finding paragraph boundaries (@pxref{Paragraphs}).  For more
        !          7697: control, you can use @kbd{M-x fill-region-as-paragraph}, which refills
        !          7698: everything between point and mark.  This command recognizes no paragraph
        !          7699: separators; it deletes any blank lines found within the region to be
        !          7700: filled.@refill
        !          7701: 
        !          7702: @cindex justification
        !          7703:   A numeric argument to @kbd{M-g} or @kbd{M-q} causes it to @dfn{justify}
        !          7704: the text as well as filling it.  This means that extra spaces are inserted
        !          7705: to make the right margin line up exactly at the fill column.  To remove the
        !          7706: extra spaces, use @kbd{M-q} or @kbd{M-g} with no argument.@refill
        !          7707: 
        !          7708: @kindex M-s
        !          7709: @cindex centering
        !          7710: @findex center-line
        !          7711:   The command @kbd{Meta-s} (@code{center-line}) centers the current line
        !          7712: within the current fill column.  With an argument, it centers several lines
        !          7713: individually and moves past them.
        !          7714: 
        !          7715: @vindex fill-column
        !          7716:   The maximum line width for filling is in the variable @code{fill-column}.
        !          7717: Altering the value of @code{fill-column} makes it local to the current
        !          7718: buffer; until that time, the default value is in effect.  The default is
        !          7719: initially 70.  @xref{Locals}.
        !          7720: 
        !          7721: @kindex C-x f
        !          7722: @findex set-fill-column
        !          7723:   The easiest way to set @code{fill-column} is to use the command @kbd{C-x
        !          7724: f} (@code{set-fill-column}).  With no argument, it sets @code{fill-column}
        !          7725: to the current horizontal position of point.  With a numeric argument, it
        !          7726: uses that as the new fill column.
        !          7727: 
        !          7728: @node Fill Prefix,, Fill Commands, Filling
        !          7729: @subsection The Fill Prefix
        !          7730: 
        !          7731: @cindex fill prefix
        !          7732:   To fill a paragraph in which each line starts with a special marker
        !          7733: (which might be a few spaces, giving an indented paragraph), use the
        !          7734: @dfn{fill prefix} feature.  The fill prefix is a string which Emacs expects
        !          7735: every line to start with, and which is not included in filling.
        !          7736: 
        !          7737: @table @kbd
        !          7738: @item C-x .
        !          7739: Set the fill prefix (@code{set-fill-prefix}).
        !          7740: @item M-q
        !          7741: Fill a paragraph using current fill prefix (@code{fill-paragraph}).
        !          7742: @item M-x fill-individual-paragraphs
        !          7743: Fill the region, considering each change of indentation as starting a
        !          7744: new paragraph.
        !          7745: @end table
        !          7746: 
        !          7747: @kindex C-x .
        !          7748: @findex set-fill-prefix
        !          7749:   To specify a fill prefix, move to a line that starts with the desired
        !          7750: prefix, put point at the end of the prefix, and give the command
        !          7751: @w{@kbd{C-x .}}@: (@code{set-fill-prefix}).  That's a period after the
        !          7752: @kbd{C-x}.  To turn off the fill prefix, specify an empty prefix: type
        !          7753: @w{@kbd{C-x .}}@: with point at the beginning of a line.
        !          7754: 
        !          7755:   When a fill prefix is in effect, the fill commands remove the fill prefix
        !          7756: from each line before filling and insert it on each line after filling.
        !          7757: The fill prefix is also inserted on new lines made automatically by Auto
        !          7758: Fill mode.  Lines that do not start with the fill prefix are considered to
        !          7759: start paragraphs, both in @kbd{M-q} and the paragraph commands; this is
        !          7760: just right if you are using paragraphs with hanging indentation (every line
        !          7761: indented except the first one).  Lines which are blank or indented once the
        !          7762: prefix is removed also separate or start paragraphs; this is what you want
        !          7763: if you are writing multi-paragraph comments with a comment delimiter on
        !          7764: each line.
        !          7765: 
        !          7766: @vindex fill-prefix
        !          7767:   The fill prefix is stored in the variable @code{fill-prefix}.  Its value
        !          7768: is a string, or @code{nil} when there is no fill prefix.  This is a
        !          7769: per-buffer variable; altering the variable affects only the current buffer,
        !          7770: but there is a default value which you can change as well.  @xref{Locals}.
        !          7771: 
        !          7772: @findex fill-individual-paragraphs
        !          7773:   Another way to use fill prefixes is through @kbd{M-x
        !          7774: fill-individual-paragraphs}.  This function divides the region into groups
        !          7775: of consecutive lines with the same amount and kind of indentation and fills
        !          7776: each group as a paragraph using its indentation as a fill prefix.
        !          7777: 
        !          7778: @node Case,, Filling, Text
        !          7779: @section Case Conversion Commands
        !          7780: @cindex case conversion
        !          7781: 
        !          7782:   Emacs has commands for converting either a single word or any arbitrary
        !          7783: range of text to upper case or to lower case.
        !          7784: 
        !          7785: @c WideCommands
        !          7786: @table @kbd
        !          7787: @item M-l
        !          7788: Convert following word to lower case (@code{downcase-word}).
        !          7789: @item M-u
        !          7790: Convert following word to upper case (@code{upcase-word}).
        !          7791: @item M-c
        !          7792: Capitalize the following word (@code{capitalize-word}).
        !          7793: @item C-x C-l
        !          7794: Convert region to lower case (@code{downcase-region}).
        !          7795: @item C-x C-u
        !          7796: Convert region to upper case (@code{upcase-region}).
        !          7797: @end table
        !          7798: 
        !          7799: @kindex M-l
        !          7800: @kindex M-u
        !          7801: @kindex M-c
        !          7802: @cindex words
        !          7803: @findex downcase-word
        !          7804: @findex upcase-word
        !          7805: @findex capitalize-word
        !          7806:   The word conversion commands are the most useful.  @kbd{Meta-l}
        !          7807: (@code{downcase-word}) converts the word after point to lower case,
        !          7808: moving past it.  Thus, repeating @kbd{Meta-l} converts successive
        !          7809: words.  @kbd{Meta-u} (@code{upcase-word}) converts to all capitals
        !          7810: instead, while @kbd{Meta-c} (@code{capitalize-word}) puts the letter
        !          7811: following point into upper case and the rest of the letters in the
        !          7812: word into lower case.  All these commands convert several words at
        !          7813: once if given an argument.  They are especially convenient for
        !          7814: converting a large amount of text from all upper case to mixed case,
        !          7815: because you can move through the text using @kbd{M-l}, @kbd{M-u} or
        !          7816: @kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f}
        !          7817: instead to skip a word.
        !          7818: 
        !          7819:   When given a negative argument, the word case conversion commands apply
        !          7820: to the appropriate number of words before point, but do not move point.
        !          7821: This is convenient when you have just typed a word in the wrong case: you
        !          7822: can give the case conversion command and continue typing.
        !          7823: 
        !          7824:   If a word case conversion command is given in the middle of a word, it
        !          7825: applies only to the part of the word which follows point.  This is just
        !          7826: like what @kbd{Meta-d} (@code{kill-word}) does.  With a negative argument,
        !          7827: case conversion applies only to the part of the word before point.
        !          7828: 
        !          7829: @kindex C-x C-l
        !          7830: @kindex C-x C-u
        !          7831: @cindex region
        !          7832: @findex downcase-region
        !          7833: @findex upcase-region
        !          7834:   The other case conversion commands are @kbd{C-x C-u}
        !          7835: (@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which
        !          7836: convert everything between point and mark to the specified case.  Point and
        !          7837: mark do not move.@refill
        !          7838: 
        !          7839: @node Programs, Compiling/Testing, Text, Top
        !          7840: @chapter Editing Programs
        !          7841: 
        !          7842:   Emacs has many commands designed to understand the syntax of programming
        !          7843: languages such as Lisp and C.  These commands can
        !          7844: 
        !          7845: @itemize @bullet
        !          7846: @item
        !          7847: Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}).
        !          7848: @item
        !          7849: Move over or mark top-level balanced expressions (@dfn{defuns}, in Lisp;
        !          7850: functions, in C).
        !          7851: @item
        !          7852: Show how parentheses balance (@pxref{Matching}).
        !          7853: @item
        !          7854: Insert, kill or align comments (@pxref{Comments}).
        !          7855: @item
        !          7856: Follow the usual indentation conventions of the language
        !          7857: (@pxref{Grinding}).
        !          7858: @end itemize
        !          7859: 
        !          7860:   The commands for words, sentences and paragraphs are very useful in
        !          7861: editing code even though their canonical application is for editing human
        !          7862: language text.  Most symbols contain words (@pxref{Words}); sentences can
        !          7863: be found in strings and comments (@pxref{Sentences}).  Paragraphs per se
        !          7864: are not present in code, but the paragraph commands are useful anyway,
        !          7865: because Lisp mode and C mode define paragraphs to begin and end at blank
        !          7866: lines (@pxref{Paragraphs}).  Judicious use of blank lines to make the
        !          7867: program clearer will also provide interesting chunks of text for the
        !          7868: paragraph commands to work on.
        !          7869: 
        !          7870:   The selective display feature is useful for looking at the overall
        !          7871: structure of a function (@pxref{Selective Display}).  This feature causes
        !          7872: only the lines that are indented less than a specified amount to appear
        !          7873: on the screen.
        !          7874: 
        !          7875: @menu
        !          7876: * Program Modes::       Major modes for editing programs.
        !          7877: * Lists::               Expressions with balanced parentheses.
        !          7878:                          There are editing commands to operate on them.
        !          7879: * Defuns::              Each program is made up of separate functions.
        !          7880:                          There are editing commands to operate on them.
        !          7881: * Grinding::            Adjusting indentation to show the nesting.
        !          7882: * Matching::            Insertion of a close-delimiter flashes matching open.
        !          7883: * Comments::            Inserting, killing and aligning comments.
        !          7884: * Macro Expansion::    How to see the results of C macro expansion.
        !          7885: * Balanced Editing::    Inserting two matching parentheses at once, etc.
        !          7886: * Lisp Completion::     Completion on symbol names in Lisp code.
        !          7887: * Documentation::       Getting documentation of functions you plan to call.
        !          7888: * Change Log::          Maintaining a change history for your program.
        !          7889: * Tags::                Go direct to any function in your program in one
        !          7890:                          command.  Tags remembers which file it is in.
        !          7891: * Fortran::            Fortran mode and its special features.
        !          7892: @end menu
        !          7893: 
        !          7894: @node Program Modes, Lists, Programs, Programs
        !          7895: @section Major Modes for Programming Languages
        !          7896: 
        !          7897: @cindex Lisp mode
        !          7898: @cindex C mode
        !          7899: @cindex Scheme mode
        !          7900:   Emacs has major modes for the programming languages Lisp, Scheme (a
        !          7901: variant of Lisp), C, Fortran and Muddle.  Ideally, a major mode should be
        !          7902: implemented for each programming language that you might want to edit with
        !          7903: Emacs; but often the mode for one language can serve for other
        !          7904: syntactically similar languages.  The language modes that exist are those
        !          7905: that someone decided to take the trouble to write.
        !          7906: 
        !          7907:   There are several forms of Lisp mode, which differ in the way they
        !          7908: interface to Lisp execution.  @xref{Lisp Modes}.
        !          7909: 
        !          7910:   Each of the programming language modes defines the @key{TAB} key to run
        !          7911: an indentation function that knows the indentation conventions of that
        !          7912: language and updates the current line's indentation accordingly.  For
        !          7913: example, in C mode @key{TAB} is bound to @code{c-indent-line}.  @key{LFD}
        !          7914: is normally defined to do @key{RET} followed by @key{TAB}; thus, it too
        !          7915: indents in a mode-specific fashion.
        !          7916: 
        !          7917: @kindex DEL
        !          7918: @findex backward-delete-char-untabify
        !          7919:   In most programming languages, indentation is likely to vary from line to
        !          7920: line.  So the major modes for those languages rebind @key{DEL} to treat a
        !          7921: tab as if it were the equivalent number of spaces (using the command
        !          7922: @code{backward-delete-char-untabify}).  This makes it possible to rub out
        !          7923: indentation one column at a time without worrying whether it is made up of
        !          7924: spaces or tabs.  Use @kbd{C-b C-d} to delete a tab character before point,
        !          7925: in these modes.
        !          7926: 
        !          7927:   Programming language modes define paragraphs to be separated only by
        !          7928: blank lines, so that the paragraph commands remain useful.  Auto Fill mode,
        !          7929: if enabled in a programming language major mode, indents the new lines
        !          7930: which it creates.
        !          7931: 
        !          7932: @cindex mode hook
        !          7933: @vindex c-mode-hook
        !          7934: @vindex lisp-mode-hook
        !          7935: @vindex emacs-lisp-mode-hook
        !          7936: @vindex lisp-interaction-mode-hook
        !          7937: @vindex scheme-mode-hook
        !          7938: @vindex muddle-mode-hook
        !          7939:   Turning on a major mode calls a user-supplied function called the
        !          7940: @dfn{mode hook}, which is the value of a Lisp variable.  For example,
        !          7941: turning on C mode calls the value of the variable @code{c-mode-hook} if
        !          7942: that value exists and is non-@code{nil}.  Mode hook variables for other
        !          7943: programming language modes include @code{lisp-mode-hook},
        !          7944: @code{emacs-lisp-mode-hook}, @code{lisp-interaction-mode-hook},
        !          7945: @code{scheme-mode-hook} and @code{muddle-mode-hook}.  The mode hook
        !          7946: function receives no arguments.@refill
        !          7947: 
        !          7948: @node Lists, Defuns, Program Modes, Programs
        !          7949: @section Lists and Sexps
        !          7950: 
        !          7951: @cindex Control-Meta
        !          7952:   By convention, Emacs keys for dealing with balanced expressions are
        !          7953: usually @kbd{Control-Meta-} characters.  They tend to be analogous in
        !          7954: function to their @kbd{Control-} and @kbd{Meta-} equivalents.  These commands
        !          7955: are usually thought of as pertaining to expressions in programming
        !          7956: languages, but can be useful with any language in which some sort of
        !          7957: parentheses exist (including English).
        !          7958: 
        !          7959: @cindex list
        !          7960: @cindex sexp
        !          7961: @cindex expression
        !          7962:   These commands fall into two classes.  Some deal only with @dfn{lists}
        !          7963: (parenthetical groupings).  They see nothing except parentheses, brackets,
        !          7964: braces (whichever ones must balance in the language you are working with),
        !          7965: and escape characters that might be used to quote those.
        !          7966: 
        !          7967:   The other commands deal with expressions or @dfn{sexps}.  The word `sexp'
        !          7968: is derived from @dfn{s-expression}, the ancient term for an expression in
        !          7969: Lisp.  But in Emacs, the notion of `sexp' is not limited to Lisp.  It
        !          7970: refers to an expression in whatever language your program is written in.
        !          7971: Each programming language has its own major mode, which customizes the
        !          7972: syntax tables so that expressions in that language count as sexps.
        !          7973: 
        !          7974:   Sexps typically include symbols, numbers, and string constants, as well
        !          7975: as anything contained in parentheses, brackets or braces.
        !          7976: 
        !          7977:   In languages that use prefix and infix operators, such as C, it is not
        !          7978: possible for all expressions to be sexps.  For example, C mode does not
        !          7979: recognize @samp{foo + bar} as a sexp, even though it @i{is} a C expression;
        !          7980: it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the
        !          7981: @samp{+} as punctuation between them.  This is a fundamental ambiguity:
        !          7982: both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to
        !          7983: move over if point is at the @samp{f}.  Note that @samp{(foo + bar)} is a
        !          7984: sexp in C mode.
        !          7985: 
        !          7986:   Some languages have obscure forms of syntax for expressions that nobody
        !          7987: has bothered to make Emacs understand properly.
        !          7988: 
        !          7989: @c doublewidecommands
        !          7990: @table @kbd
        !          7991: @item C-M-f
        !          7992: Move forward over a sexp (@code{forward-sexp}).
        !          7993: @item C-M-b
        !          7994: Move backward over a sexp (@code{backward-sexp}).
        !          7995: @item C-M-k
        !          7996: Kill sexp forward (@code{kill-sexp}).
        !          7997: @item C-M-u
        !          7998: Move up and backward in list structure (@code{backward-up-list}).
        !          7999: @item C-M-d
        !          8000: Move down and forward in list structure (@code{down-list}).
        !          8001: @item C-M-n
        !          8002: Move forward over a list (@code{forward-list}).
        !          8003: @item C-M-p
        !          8004: Move backward over a list (@code{backward-list}).
        !          8005: @item C-M-t
        !          8006: Transpose expressions (@code{transpose-sexps}).
        !          8007: @item C-M-@@
        !          8008: Put mark after following expression (@code{mark-sexp}).
        !          8009: @end table
        !          8010: 
        !          8011: @kindex C-M-f
        !          8012: @kindex C-M-b
        !          8013: @findex forward-sexp
        !          8014: @findex backward-sexp
        !          8015:   To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}).  If
        !          8016: the first significant character after point is an opening delimiter
        !          8017: (@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f}
        !          8018: moves past the matching closing delimiter.  If the character begins a
        !          8019: symbol, string, or number, @kbd{C-M-f} moves over that.  If the character
        !          8020: after point is a closing delimiter, @kbd{C-M-f} gets an error.
        !          8021: 
        !          8022:   The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
        !          8023: sexp.  The detailed rules are like those above for @kbd{C-M-f}, but with
        !          8024: directions reversed.  If there are any prefix characters (singlequote,
        !          8025: backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back
        !          8026: over them as well.
        !          8027: 
        !          8028:   @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
        !          8029: specified number of times; with a negative argument, it moves in the
        !          8030: opposite direction.
        !          8031: 
        !          8032:   The sexp commands move across comments as if they were whitespace, in
        !          8033: languages such as C where the comment-terminator can be recognized.  In
        !          8034: Lisp, and other languages where comments run until the end of a line, it is
        !          8035: very difficult to ignore comments when parsing backwards; therefore, in
        !          8036: such languages the sexp commands treat the text of comments as if it were
        !          8037: code.
        !          8038: 
        !          8039: @kindex C-M-k
        !          8040: @findex kill-sexp
        !          8041:   Killing a sexp at a time can be done with @kbd{C-M-k} (@code{kill-sexp}).
        !          8042: @kbd{C-M-k} kills the characters that @kbd{C-M-f} would move over.
        !          8043: 
        !          8044: @kindex C-M-n
        !          8045: @kindex C-M-p
        !          8046: @findex forward-list
        !          8047: @findex backward-list
        !          8048:   The @dfn{list commands} move over lists like the sexp commands but skip
        !          8049: blithely over any number of other kinds of sexps (symbols, strings, etc).
        !          8050: They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p}
        !          8051: (@code{backward-list}).  The main reason they are useful is that they
        !          8052: usually ignore comments (since the comments usually do not contain any
        !          8053: lists).@refill
        !          8054: 
        !          8055: @kindex C-M-u
        !          8056: @kindex C-M-d
        !          8057: @findex backward-up-list
        !          8058: @findex down-list
        !          8059:   @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when
        !          8060: that's possible.  To move @i{up} one (or @var{n}) levels, use @kbd{C-M-u}
        !          8061: (@code{backward-up-list}).
        !          8062: @kbd{C-M-u} moves backward up past one unmatched opening delimiter.  A
        !          8063: positive argument serves as a repeat count; a negative argument reverses
        !          8064: direction of motion and also requests repetition, so it moves forward and
        !          8065: up one or more levels.@refill
        !          8066: 
        !          8067:   To move @i{down} in list structure, use @kbd{C-M-d} (@code{down-list}).  In Lisp mode,
        !          8068: where @samp{(} is the only opening delimiter, this is nearly the same as
        !          8069: searching for a @samp{(}.  An argument specifies the number of levels
        !          8070: of parentheses to go down.
        !          8071: 
        !          8072: @cindex transposition
        !          8073: @kindex C-M-t
        !          8074: @findex transpose-sexps
        !          8075:   A somewhat random-sounding command which is nevertheless easy to use is
        !          8076: @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp across
        !          8077: the next one.  An argument serves as a repeat count, and a negative
        !          8078: argument drags backwards (thus canceling out the effect of @kbd{C-M-t} with
        !          8079: a positive argument).  An argument of zero, rather than doing nothing,
        !          8080: transposes the sexps ending after point and the mark.
        !          8081: 
        !          8082: @kindex C-M-@@
        !          8083: @findex mark-sexp
        !          8084:   To make the region be the next sexp in the buffer, use @kbd{C-M-@@}
        !          8085: (@code{mark-sexp}) which sets mark at the same place that @kbd{C-M-f} would
        !          8086: move to.  @kbd{C-M-@@} takes arguments like @kbd{C-M-f}.  In particular, a
        !          8087: negative argument is useful for putting the mark at the beginning of the
        !          8088: previous sexp.
        !          8089: 
        !          8090:   The list and sexp commands' understanding of syntax is completely
        !          8091: controlled by the syntax table.  Any character can, for example, be
        !          8092: declared to be an opening delimiter and act like an open parenthesis.
        !          8093: @xref{Syntax}.
        !          8094: 
        !          8095: @node Defuns, Grinding, Lists, Programs
        !          8096: @section Defuns
        !          8097: @cindex defuns
        !          8098: 
        !          8099:   In Emacs, a parenthetical grouping at the top level in the buffer is
        !          8100: called a @dfn{defun}.  The name derives from the fact that most top-level
        !          8101: lists in a Lisp file are instances of the special form @code{defun}, but
        !          8102: any top-level parenthetical grouping counts as a defun in Emacs parlance
        !          8103: regardless of what its contents are, and regardless of the programming
        !          8104: language in use.  For example, in C, the body of a function definition is a
        !          8105: defun.
        !          8106: 
        !          8107: @c doublewidecommands
        !          8108: @table @kbd
        !          8109: @item C-M-a
        !          8110: Move to beginning of current or preceding defun
        !          8111: (@code{beginning-of-defun}).
        !          8112: @item C-M-e
        !          8113: Move to end of current or following defun (@code{end-of-defun}).
        !          8114: @item C-M-h
        !          8115: Put region around whole current or following defun (@code{mark-defun}).
        !          8116: @end table
        !          8117: 
        !          8118: @kindex C-M-a
        !          8119: @kindex C-M-e
        !          8120: @kindex C-M-h
        !          8121: @findex beginning-of-defun
        !          8122: @findex end-of-defun
        !          8123: @findex mark-defun
        !          8124:   The commands to move to the beginning and end of the current defun are
        !          8125: @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}).
        !          8126: 
        !          8127:   If you wish to operate on the current defun, use @kbd{C-M-h}
        !          8128: (@code{mark-defun}) which puts point at the beginning and mark at the end
        !          8129: of the current or next defun.  For example, this is the easiest way to get
        !          8130: ready to move the defun to a different place in the text.  In C mode,
        !          8131: @kbd{C-M-h} runs the function @code{mark-c-function}, which is almost the
        !          8132: same as @code{mark-defun}; the difference is that it backs up over the
        !          8133: argument declarations, function name and returned data type so that the
        !          8134: entire C function is inside the region.
        !          8135: 
        !          8136:   Emacs assumes that any open-parenthesis found in the leftmost column is
        !          8137: the start of a defun.  Therefore, @b{never put an open-parenthesis at the
        !          8138: left margin in a Lisp file unless it is the start of a top level list.
        !          8139: Never put an open-brace or other opening delimiter at the beginning of a
        !          8140: line of C code unless it starts the body of a function.}  The most likely
        !          8141: problem case is when you want an opening delimiter at the start of a line
        !          8142: inside a string.  To avoid trouble, put an escape character (@samp{\}, in C
        !          8143: and Emacs Lisp, @samp{/} in some other Lisp dialects) before the opening
        !          8144: delimiter.  It will not affect the contents of the string.
        !          8145: 
        !          8146:   In the remotest past, the original Emacs found defuns by moving upward a
        !          8147: level of parentheses until there were no more levels to go up.  This always
        !          8148: required scanning all the way back to the beginning of the buffer, even for
        !          8149: a small function.  To speed up the operation, Emacs was changed to assume
        !          8150: that any @samp{(} (or other character assigned the syntactic class of
        !          8151: opening-delimiter) at the left margin is the start of a defun.  This
        !          8152: heuristic was nearly always right and avoided the costly scan; however,
        !          8153: it mandated the convention described above.
        !          8154: 
        !          8155: @node Grinding, Matching, Defuns, Programs
        !          8156: @section Indentation for Programs
        !          8157: @cindex indentation
        !          8158: @cindex grinding
        !          8159: 
        !          8160:   The best way to keep a program properly indented (``ground'') is to use
        !          8161: Emacs to re-indent it as you change it.  Emacs has commands to indent
        !          8162: properly either a single line, a specified number of lines, or all of the
        !          8163: lines inside a single parenthetical grouping.
        !          8164: 
        !          8165: @menu
        !          8166: * Basic Indent::
        !          8167: * Multi-line Indent::   Commands to reindent many lines at once.
        !          8168: * Lisp Indent::                Specifying how each Lisp function should be indented.
        !          8169: * C Indent::           Choosing an indentation style for C code.
        !          8170: @end menu
        !          8171: 
        !          8172: @node Basic Indent, Multi-line Indent, Grinding, Grinding
        !          8173: @subsection Basic Program Indentation Commands
        !          8174: 
        !          8175: @c WideCommands
        !          8176: @table @kbd
        !          8177: @item @key{TAB}
        !          8178: Adjust indentation of current line.
        !          8179: @item @key{LFD}
        !          8180: Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}).
        !          8181: @end table
        !          8182: 
        !          8183: @kindex TAB
        !          8184: @findex c-indent-line
        !          8185: @findex lisp-indent-line
        !          8186:   The basic indentation command is @key{TAB}, which gives the current line
        !          8187: the correct indentation as determined from the previous lines.  The
        !          8188: function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line}
        !          8189: in Lisp mode, @code{c-indent-line} in C mode, etc.  These functions
        !          8190: understand different syntaxes for different languages, but they all do
        !          8191: about the same thing.  @key{TAB} in any programming language major mode
        !          8192: inserts or deletes whitespace at the beginning of the current line,
        !          8193: independent of where point is in the line.  If point is inside the
        !          8194: whitespace at the beginning of the line, @key{TAB} leaves it at the end of
        !          8195: that whitespace; otherwise, @key{TAB} leaves point fixed with respect to
        !          8196: the characters around it.
        !          8197: 
        !          8198:   Use @kbd{C-q @key{TAB}} to insert a tab at point.
        !          8199: 
        !          8200: @kindex LFD
        !          8201: @findex newline-and-indent
        !          8202:   When entering a large amount of new code, use @key{LFD} (@code{newline-and-indent}),
        !          8203: which is equivalent to a @key{RET} followed by a @key{TAB}.  @key{LFD} creates
        !          8204: a blank line, and then gives it the appropriate indentation.
        !          8205: 
        !          8206:   @key{TAB} indents the second and following lines of the body of a
        !          8207: parenthetical grouping each under the preceding one; therefore, if you
        !          8208: alter one line's indentation to be nonstandard, the lines below will tend
        !          8209: to follow it.  This is the right behavior in cases where the standard
        !          8210: result of @key{TAB} is unaesthetic.
        !          8211: 
        !          8212:   Remember that an open-parenthesis, open-brace or other opening delimiter
        !          8213: at the left margin is assumed by Emacs (including the indentation routines)
        !          8214: to be the start of a function.  Therefore, you must never have an opening
        !          8215: delimiter in column zero that is not the beginning of a function, not even
        !          8216: inside a string.  This restriction is vital for making the indentation
        !          8217: commands fast; you must simply accept it.  @xref{Defuns}, for more
        !          8218: information on this.
        !          8219: 
        !          8220: @node Multi-line Indent, Lisp Indent, Basic Indent, Grinding
        !          8221: @subsection Indenting Several Lines
        !          8222: 
        !          8223:   When you wish to re-indent several lines of code which have been altered
        !          8224: or moved to a different level in the list structure, you have several
        !          8225: commands available.
        !          8226: 
        !          8227: @table @kbd
        !          8228: @item C-M-q
        !          8229: Re-indent all the lines within one list (@code{indent-sexp}).
        !          8230: @item C-u @key{TAB}
        !          8231: Shift an entire list rigidly sideways so that its first line
        !          8232: is properly indented.
        !          8233: @item C-M-\
        !          8234: Re-indent all lines in the region (@code{indent-region}).
        !          8235: @end table
        !          8236: 
        !          8237: @kindex C-M-q
        !          8238: @findex indent-sexp
        !          8239: @findex indent-c-exp
        !          8240:   You can re-indent the contents of a single list by positioning point
        !          8241: before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in
        !          8242: Lisp mode, @code{indent-c-exp} in C mode; also bound to other suitable
        !          8243: functions in other modes).  The indentation of the line the sexp starts on
        !          8244: is not changed; therefore, only the relative indentation within the list,
        !          8245: and not its position, is changed.  To correct the position as well, type a
        !          8246: @key{TAB} before the @kbd{C-M-q}.
        !          8247: 
        !          8248: @kindex C-u TAB
        !          8249:   If the relative indentation within a list is correct but the indentation
        !          8250: of its beginning is not, go to the line the list begins on and type
        !          8251: @kbd{C-u @key{TAB}}.  When @key{TAB} is given a numeric argument, it moves all the
        !          8252: lines in the grouping starting on the current line sideways the same amount
        !          8253: that the current line moves.  It is clever, though, and does not move lines
        !          8254: that start inside strings, or C preprocessor lines when in C mode.
        !          8255: 
        !          8256: @kindex C-M-\
        !          8257: @findex indent-region
        !          8258:   Another way to specify the range to be re-indented is with point and
        !          8259: mark.  The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to every line
        !          8260: whose first character is between point and mark.
        !          8261: 
        !          8262: @node Lisp Indent, C Indent, Multi-line Indent, Grinding
        !          8263: @subsection Customizing Lisp Indentation
        !          8264: @cindex customization
        !          8265: 
        !          8266:   The indentation pattern for a Lisp expression can depend on the function
        !          8267: called by the expression.  For each Lisp function, you can choose among
        !          8268: several predefined patterns of indentation, or define an arbitrary one with
        !          8269: a Lisp program.
        !          8270: 
        !          8271:   The standard pattern of indentation is as follows: the second line of the
        !          8272: expression is indented under the first argument, if that is on the same
        !          8273: line as the beginning of the expression; otherwise, the second line is
        !          8274: indented underneath the function name.  Each following line is indented
        !          8275: under the previous line whose nesting depth is the same.
        !          8276: 
        !          8277: @vindex lisp-indent-offset
        !          8278:   If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
        !          8279: the usual indentation pattern for the second line of an expression, so that
        !          8280: such lines are always indented @code{lisp-indent-offset} more columns than
        !          8281: the containing list.
        !          8282: 
        !          8283: @vindex lisp-body-indent
        !          8284:   The standard pattern is overridden for certain functions.  Functions
        !          8285: whose names start with @code{def} always indent the second line by
        !          8286: @code{lisp-body-indention} extra columns beyond the open-parenthesis
        !          8287: starting the expression.
        !          8288: 
        !          8289:   The standard pattern can be overridden in various ways for individual
        !          8290: functions, according to the @code{lisp-indent-hook} property of the
        !          8291: function name.  There are four possibilities for this property:
        !          8292: 
        !          8293: @table @asis
        !          8294: @item @code{nil}
        !          8295: This is the same as no property; the standard indentation pattern is used.
        !          8296: @item @code{defun}
        !          8297: The pattern used for function names that start with @code{def} is used for
        !          8298: this function also.
        !          8299: @item a number, @var{number}
        !          8300: The first @var{number} arguments of the function are
        !          8301: @dfn{distinguished} arguments; the rest are considered the @dfn{body}
        !          8302: of the expression.  A line in the expression is indented according to
        !          8303: whether the first argument on it is distinguished or not.  If the
        !          8304: argument is part of the body, the line is indented @code{lisp-body-indent}
        !          8305: more columns than the open-parenthesis starting the containing
        !          8306: expression.  If the argument is distinguished and is either the first
        !          8307: or second argument, it is indented @i{twice} that many extra columns.
        !          8308: If the argument is distinguished and not the first or second argument,
        !          8309: the standard pattern is followed for that line.
        !          8310: @item a symbol, @var{symbol}
        !          8311: @var{symbol} should be a function name; that function is called to
        !          8312: calculate the indentation of a line within this expression.  The
        !          8313: function receives two arguments:
        !          8314: @table @asis
        !          8315: @item @var{state}
        !          8316: The value returned by @code{parse-partial-sexp} (a Lisp primitive for
        !          8317: indentation and nesting computation) when it parses up to the
        !          8318: beginning of this line.
        !          8319: @item @var{pos}
        !          8320: The position at which the line being indented begins.
        !          8321: @end table
        !          8322: @noindent
        !          8323: It should return either a number, which is the number of columns of
        !          8324: indentation for that line, or a list whose @sc{car} is such a number.  The
        !          8325: difference between returning a number and returning a list is that a
        !          8326: number says that all following lines at the same nesting level should
        !          8327: be indented just like this one; a list says that following lines might
        !          8328: call for different indentations.  This makes a difference when the
        !          8329: indentation is being computed by @kbd{C-M-q}; if the value is a
        !          8330: number, @kbd{C-M-q} need not recalculate indentation for the following
        !          8331: lines until the end of the list.
        !          8332: @end table
        !          8333: 
        !          8334: @node C Indent,, Lisp Indent, Grinding
        !          8335: @subsection Customizing C Indentation
        !          8336: 
        !          8337:   Two variables control which commands perform C indentation and when.
        !          8338: 
        !          8339: @vindex c-auto-newline
        !          8340:   If @code{c-auto-newline} is non-@code{nil}, newlines are inserted both
        !          8341: before and after braces that you insert, and after colons and semicolons.
        !          8342: Correct C indentation is done on all the lines that are made this way.
        !          8343: 
        !          8344: @vindex c-tab-always-indent
        !          8345:   If @code{c-tab-always-indent} is @code{nil}, the @key{TAB} command
        !          8346: in C mode does indentation only if point is at the left margin or within
        !          8347: the line's indentation.  If there is non-whitespace to the left of point,
        !          8348: then @key{TAB} just inserts a tab character in the buffer.  Normally,
        !          8349: this variable is @code{t}, and @key{TAB} always reindents the current line.
        !          8350: 
        !          8351:   C does not have anything analogous to particular function names for which
        !          8352: special forms of indentation are desirable.  However, it has a different
        !          8353: need for customization facilities: many different styles of C indentation
        !          8354: are in common use.
        !          8355: 
        !          8356:   There are six variables you can set to control the style that Emacs C
        !          8357: mode will use.
        !          8358: 
        !          8359: @table @code
        !          8360: @item c-indent-level
        !          8361: Indentation of C statements within surrounding block.  The surrounding
        !          8362: block's indentation is the indentation of the line on which the
        !          8363: open-brace appears.
        !          8364: @item c-continued-statement-offset
        !          8365: Extra indentation given to a substatement, such as the then-clause of
        !          8366: an if or body of a while.
        !          8367: @item c-brace-offset
        !          8368: Extra indentation for line if it starts with an open brace.
        !          8369: @item c-brace-imaginary-offset
        !          8370: An open brace following other text is treated as if it were this far
        !          8371: to the right of the start of its line.
        !          8372: @item c-argdecl-indent
        !          8373: Indentation level of declarations of C function arguments.
        !          8374: @item c-label-offset
        !          8375: Extra indentation for line that is a label, or case or default.
        !          8376: @end table
        !          8377: 
        !          8378: @vindex c-indent-level
        !          8379:   The variable @code{c-indent-level} controls the indentation for C
        !          8380: statements with respect to the surrounding block.  In the example
        !          8381: 
        !          8382: @example
        !          8383:     @{
        !          8384:       foo ();
        !          8385: @end example
        !          8386: 
        !          8387: @noindent
        !          8388: the difference in indentation between the lines is @code{c-indent-level}.
        !          8389: Its standard value is 2.
        !          8390: 
        !          8391: If the open-brace beginning the compound statement is not at the beginning
        !          8392: of its line, the @code{c-indent-level} is added to the indentation of the
        !          8393: line, not the column of the open-brace.  For example,
        !          8394: 
        !          8395: @example
        !          8396: if (losing) @{
        !          8397:   do_this ();
        !          8398: @end example
        !          8399: 
        !          8400: @noindent
        !          8401: One popular indentation style is that which results from setting
        !          8402: @code{c-indent-level} to 8 and putting open-braces at the end of a line in
        !          8403: this way.  I prefer to put the open-brace on a separate line.
        !          8404: 
        !          8405: @vindex c-brace-imaginary-offset
        !          8406:   In fact, the value of the variable @code{c-brace-imaginary-offset} is
        !          8407: also added to the indentation of such a statement.  Normally this variable
        !          8408: is zero.  Think of this variable as the imaginary position of the open
        !          8409: brace, relative to the first nonblank character on the line.  By setting
        !          8410: this variable to 4 and @code{c-indent-level} to 0, you can get this style:
        !          8411: 
        !          8412: @example
        !          8413: if (x == y) @{
        !          8414:     do_it ();
        !          8415:     @}
        !          8416: @end example
        !          8417: 
        !          8418:   When @code{c-indent-level} is zero, the statements inside most braces
        !          8419: will line up right under the open brace.  But there is an exception made
        !          8420: for braces in column zero, such as surrounding a function's body.  The
        !          8421: statements just inside it do not go at column zero.  Instead,
        !          8422: @code{c-brace-offset} and @w{@code{c-continued-statement-offset}} (see below)
        !          8423: are added to produce a typical offset between brace levels, and the
        !          8424: statements are indented that far.
        !          8425: 
        !          8426: @vindex c-continued-statement-offset
        !          8427:   @code{c-continued-statement-offset} controls the extra indentation for a
        !          8428: line that starts within a statement (but not within parentheses or
        !          8429: brackets).  These lines are usually statements that are within other
        !          8430: statements, such as the then-clauses of @code{if} statements and the bodies
        !          8431: of @code{while} statements.  This parameter is the difference in
        !          8432: indentation between the two lines in
        !          8433: 
        !          8434: @example
        !          8435: if (x == y)
        !          8436:   do_it ();
        !          8437: @end example
        !          8438: 
        !          8439: @noindent
        !          8440: Its standard value is 2.  Some popular indentation styles correspond to a
        !          8441: value of zero for @code{c-continued-statement-offset}.
        !          8442: 
        !          8443: @vindex c-brace-offset
        !          8444:   @code{c-brace-offset} is the extra indentation given to a line that
        !          8445: starts with an open-brace.  Its standard value is zero;
        !          8446: compare
        !          8447: 
        !          8448: @example
        !          8449: if (x == y)
        !          8450:   @{
        !          8451: @end example
        !          8452: 
        !          8453: @noindent
        !          8454: with
        !          8455: 
        !          8456: @example
        !          8457: if (x == y)
        !          8458:   do_it ();
        !          8459: @end example
        !          8460: 
        !          8461: @noindent
        !          8462: if @code{c-brace-offset} were set to 4, the first example would become
        !          8463: 
        !          8464: @example
        !          8465: if (x == y)
        !          8466:       @{
        !          8467: @end example
        !          8468: 
        !          8469: @vindex c-argdecl-indent
        !          8470:   @code{c-argdecl-indent} controls the indentation of declarations of the
        !          8471: arguments of a C function.  It is absolute: argument declarations receive
        !          8472: exactly @code{c-argdecl-indent} spaces.  The standard value is 5, resulting
        !          8473: in code like this:
        !          8474: 
        !          8475: @example
        !          8476: char *
        !          8477: index (string, c)
        !          8478:      char *string;
        !          8479:      int c;
        !          8480: @end example
        !          8481: 
        !          8482: @vindex c-label-offset
        !          8483:   @code{c-label-offset} is the extra indentation given to a line that
        !          8484: contains a label, a case statement, or a @code{default:} statement.  Its
        !          8485: standard value is @minus{}2, resulting in code like this
        !          8486: 
        !          8487: @example
        !          8488: switch (c)
        !          8489:   @{
        !          8490:   case 'x':
        !          8491: @end example
        !          8492: 
        !          8493: @noindent
        !          8494: If @code{c-label-offset} were zero, the same code would be indented as
        !          8495: 
        !          8496: @example
        !          8497: switch (c)
        !          8498:   @{
        !          8499:     case 'x':
        !          8500: @end example
        !          8501: 
        !          8502: @noindent
        !          8503: This example assumes that the other variables above also have their
        !          8504: standard values.
        !          8505: 
        !          8506:   I strongly recommend that you try out the indentation style produced by
        !          8507: the standard settings of these variables, together with putting open braces
        !          8508: on separate lines.  You can see how it looks in all the C source files of
        !          8509: GNU Emacs.
        !          8510: 
        !          8511: @node Matching, Comments, Grinding, Programs
        !          8512: @section Automatic Display Of Matching Parentheses
        !          8513: @cindex matching parentheses
        !          8514: @cindex parentheses
        !          8515: 
        !          8516:   The Emacs parenthesis-matching feature is designed to show automatically
        !          8517: how parentheses match in the text.  Whenever a self-inserting character
        !          8518: that is a closing delimiter is typed, the cursor moves momentarily to the
        !          8519: location of the matching opening delimiter, provided that is on the screen.
        !          8520: If it is not on the screen, some text starting with that opening delimiter
        !          8521: is displayed in the echo area.  Either way, you can tell what grouping is
        !          8522: being closed off.
        !          8523: 
        !          8524:   In Lisp, automatic matching applies only to parentheses.  In C, it
        !          8525: applies to braces and brackets too.  Emacs knows which characters to regard
        !          8526: as matching delimiters based on the syntax table, which is set by the major
        !          8527: mode.  @xref{Syntax}.
        !          8528: 
        !          8529:   If the opening delimiter and closing delimiter are mismatched---such as
        !          8530: in @samp{[x)}---a warning message is displayed in the echo area.  The
        !          8531: correct matches are specified in the syntax table.
        !          8532: 
        !          8533: @vindex blink-matching-paren
        !          8534: @vindex blink-matching-paren-distance
        !          8535:   Two variables control parenthesis match display.  @code{blink-matching-paren}
        !          8536: turns the feature on or off; @code{nil} turns it off, but the default is
        !          8537: @code{t} to turn match display on.  @code{blink-matching-paren-distance}
        !          8538: specifies how many characters back to search to find the matching opening
        !          8539: delimiter.  If the match is not found in that far, scanning stops, and
        !          8540: nothing is displayed.  This is to prevent scanning for the matching
        !          8541: delimiter from wasting lots of time when there is no match.  The default
        !          8542: is 4000.
        !          8543: 
        !          8544: @node Comments, Macro Expansion, Matching, Programs
        !          8545: @section Manipulating Comments
        !          8546: @cindex comments
        !          8547: @kindex M-;
        !          8548: @cindex indentation
        !          8549: @findex indent-for-comment
        !          8550: 
        !          8551:   The comment commands insert, kill and align comments.
        !          8552: 
        !          8553: @c WideCommands
        !          8554: @table @kbd
        !          8555: @item M-;
        !          8556: Insert or align comment (@code{indent-for-comment}).
        !          8557: @item C-x ;
        !          8558: Set comment column (@code{set-comment-column}).
        !          8559: @item C-u - C-x ;
        !          8560: Kill comment on current line (@code{kill-comment}).
        !          8561: @item M-@key{LFD}
        !          8562: Like @key{RET} followed by inserting and aligning a comment
        !          8563: (@code{indent-new-comment-line}).
        !          8564: @end table
        !          8565: 
        !          8566:   The command that creates a comment is @kbd{Meta-;} (@code{indent-for-comment}).
        !          8567: If there is no comment already on the line, a new comment is created,
        !          8568: aligned at a specific column called the @dfn{comment column}.  The comment
        !          8569: is created by inserting the string Emacs thinks comments should start with
        !          8570: (the value of @code{comment-start}; see below).  Point is left after that
        !          8571: string.  If the text of the line extends past the comment column, then the
        !          8572: indentation is done to a suitable boundary (usually, at least one space is
        !          8573: inserted).  If the major mode has specified a string to terminate comments,
        !          8574: that is inserted after point, to keep the syntax valid.
        !          8575: 
        !          8576:   @kbd{Meta-;} can also be used to align an existing comment.  If a line
        !          8577: already contains the string that starts comments, then @kbd{M-;} just moves
        !          8578: point after it and re-indents it to the conventional place.  Exception:
        !          8579: comments starting in column 0 are not moved.
        !          8580: 
        !          8581:   Some major modes have special rules for indenting certain kinds of
        !          8582: comments in certain contexts.  For example, in Lisp code, comments which
        !          8583: start with two semicolons are indented as if they were lines of code,
        !          8584: instead of at the comment column.  Comments which start with three
        !          8585: semicolons are supposed to start at the left margin.  Emacs understands
        !          8586: these conventions by indenting a double-semicolon comment using @key{TAB},
        !          8587: and by not changing the indentation of a triple-semicolon comment at all.
        !          8588: 
        !          8589: @example
        !          8590: ;; This function is just an example
        !          8591: ;;; Here either two or three semicolons are appropriate.
        !          8592: (defun foo (x)
        !          8593: ;;; And now, the first part of the function:
        !          8594:   ;; The following line adds one.
        !          8595:   (1+ x))           ; This line adds one.
        !          8596: @end example
        !          8597: 
        !          8598:   In C code, a comment preceded on its line by nothing but whitespace
        !          8599: is indented like a line of code.
        !          8600: 
        !          8601:   Even when an existing comment is properly aligned, @kbd{M-;} is still
        !          8602: useful for moving directly to the start of the comment.
        !          8603: 
        !          8604: @kindex C-u - C-x ;
        !          8605: @findex kill-comment
        !          8606:   @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
        !          8607: if there is one.  The indentation before the start of the comment is killed
        !          8608: as well.  If there does not appear to be a comment in the line, nothing is
        !          8609: done.  To reinsert the comment on another line, move to the end of that
        !          8610: line, do @kbd{C-y}, and then do @kbd{M-;} to realign it.  Note that
        !          8611: @kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
        !          8612: with a negative argument.  That command is programmed so that when it
        !          8613: receives a negative argument it calls @code{kill-comment}.  However,
        !          8614: @code{kill-comment} is a valid command which you could bind directly to a
        !          8615: key if you wanted to.
        !          8616: 
        !          8617: @subsection Multiple Lines of Comments
        !          8618: 
        !          8619: @kindex M-LFD
        !          8620: @cindex blank lines
        !          8621: @findex indent-new-comment-line
        !          8622:   If you are typing a comment and find that you wish to continue it on
        !          8623: another line, you can use the command @kbd{Meta-@key{LFD}} (@code{indent-new-comment-line}),
        !          8624: which terminates the comment you are typing, creates a new blank line
        !          8625: afterward, and begins a new comment indented under the old one.  When Auto
        !          8626: Fill mode is on, going past the fill column while typing a comment causes
        !          8627: the comment to be continued in just this fashion.  If point is not at the
        !          8628: end of the line when @kbd{M-@key{LFD}} is typed, the text on the rest of
        !          8629: the line becomes part of the new comment line.
        !          8630: 
        !          8631: @subsection Options Controlling Comments
        !          8632: 
        !          8633: @vindex comment-column
        !          8634: @kindex C-x ;
        !          8635: @findex set-comment-column
        !          8636:   The comment column is stored in the variable @code{comment-column}.  You
        !          8637: can set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
        !          8638: (@code{set-comment-column}) sets the comment column to the column point is
        !          8639: at.  @w{@kbd{C-u C-x ;}} sets the comment column to match the last comment
        !          8640: before point in the buffer, and then does a @kbd{Meta-;} to align the
        !          8641: current line's comment under the previous one.  Note that @kbd{C-u - C-x ;}
        !          8642: runs the function @code{kill-comment} as described above.
        !          8643: 
        !          8644:   @code{comment-column} is a per-buffer variable; altering the variable
        !          8645: affects only the current buffer, but there is a default value which you can
        !          8646: change as well.  @xref{Locals}.  Many major modes initialize this variable
        !          8647: for the current buffer.
        !          8648: 
        !          8649: @vindex comment-start-skip
        !          8650:   The comment commands recognize comments based on the regular expression
        !          8651: that is the value of the variable @code{comment-start-skip}.  This regexp
        !          8652: should not match the null string.  It may match more than the comment
        !          8653: starting delimiter in the strictest sense of the word; for example, in C
        !          8654: mode the value of the variable is @code{@t{"/\\*+ *"}}, which matches extra
        !          8655: stars and spaces after the @samp{/*} itself.  (Note that @samp{\\} is
        !          8656: needed in Lisp syntax to include a @samp{\} in the string, which is needed
        !          8657: to deny the first star its special meaning in regexp syntax.  @xref{Regexps}.)
        !          8658: 
        !          8659: @vindex comment-start
        !          8660: @vindex comment-end
        !          8661:   When a comment command makes a new comment, it inserts the value of
        !          8662: @code{comment-start} to begin it.  The value of @code{comment-end} is
        !          8663: inserted after point, so that it will follow the text that you will insert
        !          8664: into the comment.  In C mode, @code{comment-start} has the value
        !          8665: @w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}.
        !          8666: 
        !          8667: @vindex comment-multi-line
        !          8668:   @code{comment-multi-line} controls how @kbd{M-@key{LFD}} (@code{indent-new-comment-line})
        !          8669: behaves when used inside a comment.  If @code{comment-multi-line} is
        !          8670: @code{nil}, as it normally is, then the comment on the starting line is
        !          8671: terminated and a new comment is started on the new following line.  If
        !          8672: @code{comment-multi-line} is not @code{nil}, then the new following line is
        !          8673: set up as part of the same comment that was found on the starting line.
        !          8674: This is done by not inserting a terminator on the old line, and not
        !          8675: inserting a starter on the new line.  In languages where multi-line comments
        !          8676: work, the choice of value for this variable is a matter of taste.
        !          8677: 
        !          8678: @vindex comment-indent-hook
        !          8679:   The variable @code{comment-indent-hook} should contain a function that
        !          8680: will be called to compute the indentation for a newly inserted comment or
        !          8681: for aligning an existing comment.  It is set differently by various major
        !          8682: modes.  The function is called with no arguments, but with point at the
        !          8683: beginning of the comment, or at the end of a line if a new comment is to be
        !          8684: inserted.  It should return the column in which the comment ought to start.
        !          8685: For example, in Lisp mode, the indent hook function bases its decision
        !          8686: on how many semicolons begin an existing comment, and on the code in the
        !          8687: preceding lines.
        !          8688: 
        !          8689: @node Macro Expansion, Balanced Editing, Comments, Programs
        !          8690: @section Viewing How C Macros Expand
        !          8691: @cindex macro expansion in C
        !          8692: @cindex expansion of C macros
        !          8693: 
        !          8694: @findex c-macro-expand
        !          8695: When you are debugging C code that uses macros, sometimes it is hard to
        !          8696: figure out precisely how the macros expand.  The command @kbd{M-x
        !          8697: c-macro-expand}.  It runs the C preprocessor and shows you what
        !          8698: expansion results from the region.  The portion of the buffer before the
        !          8699: region is also included in preprocessing, for the sake of macros defined
        !          8700: there, but the output from this part isn't shown.
        !          8701: 
        !          8702: @node Balanced Editing, Lisp Completion, Macro Expansion, Programs
        !          8703: @section Editing Without Unbalanced Parentheses
        !          8704: 
        !          8705: @table @kbd
        !          8706: @item M-(
        !          8707: Put parentheses around next sexp(s) (@code{insert-parentheses}).
        !          8708: @item M-)
        !          8709: Move past next close parenthesis and re-indent
        !          8710: (@code{move-over-close-and-reindent}).
        !          8711: @end table
        !          8712: 
        !          8713: @kindex M-(
        !          8714: @kindex M-)
        !          8715: @findex insert-parentheses
        !          8716: @findex move-over-close-and-reindent
        !          8717:   The two commands, @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)}
        !          8718: (@code{move-over-close-and-reindent}), are designed to facilitate a style of
        !          8719: editing which keeps parentheses balanced at all times.  @kbd{M-(} inserts a
        !          8720: pair of parentheses, either together as in @samp{()}, or, if given an
        !          8721: argument, around the next several sexps, and leaves point after the open
        !          8722: parenthesis.  Instead of typing @w{@kbd{( F O O )}}, you can type @kbd{M-( F O
        !          8723: O}, which has the same effect except for leaving the cursor before the
        !          8724: close parenthesis.  Then you would type @kbd{M-)}, which moves past the
        !          8725: close parenthesis, deleting any indentation preceding it (in this example
        !          8726: there is none), and indenting with @key{LFD} after it.
        !          8727: 
        !          8728: @node Lisp Completion, Documentation, Balanced Editing, Programs
        !          8729: @section Completion for Lisp Symbols
        !          8730: @cindex completion (symbol names)
        !          8731: 
        !          8732:   Usually completion happens in the minibuffer.  But one kind of completion
        !          8733: is available in all buffers: completion for Lisp symbol names.
        !          8734: 
        !          8735: @kindex M-TAB
        !          8736: @findex lisp-complete-symbol
        !          8737:   The command @kbd{M-@key{TAB}} (@code{lisp-complete-symbol}) takes the
        !          8738: partial Lisp symbol before point to be an abbreviation, and compares it
        !          8739: against all nontrivial Lisp symbols currently known to Emacs.  Any
        !          8740: additional characters that they all have in common are inserted at point.
        !          8741: Nontrivial symbols are those that have function definitions, values or
        !          8742: properties.
        !          8743: 
        !          8744:   If there is an open-parenthesis immediately before the beginning of
        !          8745: the partial symbol, only symbols with function definitions are considered
        !          8746: as completions.
        !          8747: 
        !          8748:   If the partial name in the buffer has more than one possible completion
        !          8749: and they have no additional characters in common, a list of all possible
        !          8750: completions is displayed in another window.
        !          8751: 
        !          8752: @node Documentation, Change Log, Lisp Completion, Programs
        !          8753: @section Documentation Commands
        !          8754: 
        !          8755: @kindex C-h f
        !          8756: @findex describe-function
        !          8757: @kindex C-h v
        !          8758: @findex describe-variable
        !          8759:   As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f}
        !          8760: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can
        !          8761: be used to print documentation of functions and variables that you want to
        !          8762: call.  These commands use the minibuffer to read the name of a function or
        !          8763: variable to document, and display the documentation in a window.
        !          8764: 
        !          8765:   For extra convenience, these commands provide default arguments based on
        !          8766: the code in the neighborhood of point.  @kbd{C-h f} sets the default to the
        !          8767: function called in the innermost list containing point.  @kbd{C-h v} uses
        !          8768: the symbol name around or adjacent to point as its default.
        !          8769: 
        !          8770: @findex manual-entry
        !          8771:   Documentation on Unix commands, system calls and libraries can be
        !          8772: obtained with the @kbd{M-x manual-entry} command.  This reads a topic as an
        !          8773: argument, and displays the text on that topic from the Unix manual.
        !          8774: @code{manual-entry} always searches all 8 sections of the manual, and
        !          8775: concatenates all the entries that are found.  For example, the topic
        !          8776: @samp{termcap} finds the description of the termcap library from section 3,
        !          8777: followed by the description of the termcap data base from section 5.
        !          8778: 
        !          8779: @node Change Log, Tags, Documentation, Programs
        !          8780: @section Change Logs
        !          8781: 
        !          8782: @cindex change log
        !          8783: @findex add-change-log-entry
        !          8784:   The Emacs command @kbd{M-x add-change-log-entry} helps you keep a record
        !          8785: of when and why you have changed a program.  It assumes that you have a
        !          8786: file in which you write a chronological sequence of entries describing
        !          8787: individual changes.  The default is to store the change entries in a file
        !          8788: called @file{ChangeLog} in the same directory as the file you are editing.
        !          8789: The same @file{ChangeLog} file therefore records changes for all the files
        !          8790: in the directory.
        !          8791: 
        !          8792:   A change log entry starts with a header line that contains your name and
        !          8793: the current date.  Aside from these header lines, every line in the
        !          8794: change log starts with a tab.  One entry can describe several changes;
        !          8795: each change starts with a line starting with a tab and a star.
        !          8796: @kbd{M-x add-change-log-entry} visits the change log file and creates
        !          8797: a new entry unless the most recent entry is for today's date and your
        !          8798: name.  In either case, it adds a new line to start the description of
        !          8799: another change just after the header line of the entry.  When @kbd{M-x
        !          8800: add-change-log-entry} is finished, all is prepared for you to edit in
        !          8801: the description of what you changed and how.  You must then save the
        !          8802: change log file yourself.
        !          8803: 
        !          8804:   The change log file is always visited in Indented Text mode, which means
        !          8805: that @key{LFD} and auto-filling indent each new line like the previous
        !          8806: line.  This is convenient for entering the contents of an entry, which must
        !          8807: all be indented.  @xref{Text Mode}.
        !          8808: 
        !          8809: @findex add-change-log-entry-other-window
        !          8810: @kindex C-x 4 a
        !          8811:   An alternative convenient command for starting a change log entry is
        !          8812: @w{@kbd{C-x 4 a}} (@code{add-change-log-entry-other-window}).  It resembles
        !          8813: @code{add-change-log-entry} except that it visits the change log in
        !          8814: another window, and always uses the file @file{./ChangeLog}---it does
        !          8815: not ask you for the file name.
        !          8816: 
        !          8817:   Here is an example of the formatting conventions used in the change log
        !          8818: for Emacs:
        !          8819: 
        !          8820: @smallexample
        !          8821: @group
        !          8822: Wed Jun 26 19:29:32 1985  Richard M. Stallman  (rms at mit-prep)
        !          8823: 
        !          8824:         * xdisp.c (try_window_id):
        !          8825:         If C-k is done at end of next-to-last line,
        !          8826:         this fn updates window_end_vpos and cannot leave
        !          8827:         window_end_pos nonnegative (it is zero, in fact).
        !          8828:         If display is preempted before lines are output,
        !          8829:         this is inconsistent.  Fix by setting
        !          8830:         blank_end_of_window to nonzero.
        !          8831: @end group
        !          8832: 
        !          8833: @group
        !          8834: Tue Jun 25 05:25:33 1985  Richard M. Stallman  (rms at mit-prep)
        !          8835: 
        !          8836:         * cmds.c (Fnewline):
        !          8837:         Call the auto fill hook if appropriate.
        !          8838: @end group
        !          8839: 
        !          8840: @group
        !          8841:         * xdisp.c (try_window_id):
        !          8842:         If point is found by compute_motion after xp, record that
        !          8843:         permanently.  If display_text_line sets point position wrong
        !          8844:         (case where line is killed, point is at eob and that line is
        !          8845:         not displayed), set it again in final compute_motion.
        !          8846: @end group
        !          8847: @end smallexample
        !          8848: 
        !          8849: @node Tags, Fortran, Change Log, Programs
        !          8850: @section Tag Tables
        !          8851: @cindex tag table
        !          8852: 
        !          8853:   A @dfn{tag table} is a description of how a multi-file program is broken
        !          8854: up into files.  It lists the names of the component files and the names and
        !          8855: positions of the functions in each file.  Grouping the related files makes
        !          8856: it possible to search or replace through all the files with one command.
        !          8857: Recording the function names and positions makes possible the @kbd{Meta-.}
        !          8858: command which you can use to find the definition of a function without
        !          8859: having to know which of the files it is in.
        !          8860: 
        !          8861:   Tag tables are stored in files called @dfn{tag table files}.  The
        !          8862: conventional name for a tag table file is @file{TAGS}.
        !          8863: 
        !          8864:   Each entry in the tag table records the name of one tag, the name of the
        !          8865: file that the tag is defined in (implicitly), and the position in that file
        !          8866: of the tag's definition.
        !          8867: 
        !          8868:   Just what names from the described files are recorded in the tag table
        !          8869: depends on the programming language of the described file.  They normally
        !          8870: include all functions and subroutines, and may also include global
        !          8871: variables, data types, and anything else convenient.  In any case, each
        !          8872: name recorded is called a @dfn{tag}.
        !          8873: 
        !          8874: @menu
        !          8875: * Tag Syntax::
        !          8876: * Create Tag Table::
        !          8877: * Select Tag Table::
        !          8878: * Find Tag::
        !          8879: * Tags Search::
        !          8880: * Tags Stepping::
        !          8881: * List Tags::
        !          8882: @end menu
        !          8883: 
        !          8884: @node Tag Syntax, Create Tag Table, Tags, Tags
        !          8885: @subsection Source File Tag Syntax
        !          8886: 
        !          8887:   In Lisp code, any function defined with @code{defun}, any variable
        !          8888: defined with @code{defvar} or @code{defconst}, and in general the first
        !          8889: argument of any expression that starts with @samp{(def} in column zero, is
        !          8890: a tag.
        !          8891: 
        !          8892:   In C code, any C function is a tag, and so is any typedef if @code{-t} is
        !          8893: specified when the tag table is constructed.
        !          8894: 
        !          8895:   In Fortran code, functions and subroutines are tags.
        !          8896: 
        !          8897:   In La@TeX{} text, the argument of any of the commands @code{\chapter},
        !          8898: @code{\section}, @code{\subsection}, @code{\subsubsection}, @code{\eqno},
        !          8899: @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem} and
        !          8900: @code{\typeout} is a tag.@refill
        !          8901: 
        !          8902: @node Create Tag Table, Select Tag Table, Tag Syntax, Tags
        !          8903: @subsection Creating Tag Tables
        !          8904: @cindex etags program
        !          8905: 
        !          8906:   The @code{etags} program is used to create a tag table file.  It knows
        !          8907: the syntax of C, Fortran, La@TeX{}, Scheme and Emacs Lisp/Common Lisp.  To
        !          8908: use @code{etags}, type
        !          8909: 
        !          8910: @example
        !          8911: etags @var{inputfiles}@dots{}
        !          8912: @end example
        !          8913: 
        !          8914: @noindent
        !          8915: as a shell command.  It reads the specified files and writes a tag table
        !          8916: named @file{TAGS} in the current working directory.  @code{etags}
        !          8917: recognizes the language used in an input file based on its file name and
        !          8918: contents; there are no switches for specifying the language.  The @code{-t}
        !          8919: switch tells @code{etags} to record typedefs in C code as tags.
        !          8920: 
        !          8921:   If the tag table data become outdated due to changes in the files
        !          8922: described in the table, the way to update the tag table is the same way it
        !          8923: was made in the first place.  It is not necessary to do this often.
        !          8924: 
        !          8925:   If the tag table fails to record a tag, or records it for the wrong file,
        !          8926: then Emacs cannot possibly find its definition.  However, if the position
        !          8927: recorded in the tag table becomes a little bit wrong (due to some editing
        !          8928: in the file that the tag definition is in), the only consequence is to slow
        !          8929: down finding the tag slightly.  Even if the stored position is very wrong,
        !          8930: Emacs will still find the tag, but it must search the entire file for it.
        !          8931: 
        !          8932:   So you should update a tag table when you define new tags that you want
        !          8933: to have listed, or when you move tag definitions from one file to another,
        !          8934: or when changes become substantial.  Normally there is no need to update
        !          8935: the tag table after each edit, or even every day.
        !          8936: 
        !          8937: @node Select Tag Table, Find Tag, Create Tag Table, Tags
        !          8938: @subsection Selecting a Tag Table
        !          8939: 
        !          8940: @vindex tags-file-name
        !          8941: @findex visit-tags-table
        !          8942:   Emacs has at any time one @dfn{selected} tag table, and all the commands
        !          8943: for working with tag tables use the selected one.  To select a tag table,
        !          8944: type @w{@kbd{M-x visit-tags-table}}, which reads the tag table file name as an
        !          8945: argument.  The name @file{TAGS} in the default directory is used as the
        !          8946: default file name.
        !          8947: 
        !          8948:   All this command does is store the file name in the variable
        !          8949: @code{tags-file-name}.  Emacs does not actually read in the tag table
        !          8950: contents until you try to use them.  Setting this variable yourself is just
        !          8951: as good as using @code{visit-tags-table}.  The variable's initial value is
        !          8952: @code{nil}; this value tells all the commands for working with tag tables
        !          8953: that they must ask for a tag table file name to use.
        !          8954: 
        !          8955: @node Find Tag, Tags Search, Select Tag Table, Tags
        !          8956: @subsection Finding a Tag
        !          8957: 
        !          8958:   The most important thing that a tag table enables you to do is to find
        !          8959: the definition of a specific tag.
        !          8960: 
        !          8961: @table @kbd
        !          8962: @item M-.@: @var{tag}
        !          8963: Find first definition of @var{tag} (@code{find-tag}).
        !          8964: @item C-u M-.
        !          8965: Find next alternate definition of last tag specified.
        !          8966: @item C-x 4 .@: @var{tag}
        !          8967: Find first definition of @var{tag}, but display it in another window
        !          8968: (@code{find-tag-other-window}).
        !          8969: @end table
        !          8970: 
        !          8971: @kindex M-.
        !          8972: @findex find-tag
        !          8973:   @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of a
        !          8974: specified tag.  It searches through the tag table for that tag, as a
        !          8975: string, and then uses the tag table info to determine the file that the
        !          8976: definition is in and the approximate character position in the file of the
        !          8977: definition.  Then @code{find-tag} visits that file, moves point to the
        !          8978: approximate character position, and starts searching ever-increasing
        !          8979: distances away for the the text that should appear at the beginning of the
        !          8980: definition.
        !          8981: 
        !          8982:   If an empty argument is given (just type @key{RET}), the sexp in the
        !          8983: buffer before or around point is used as the name of the tag to find.
        !          8984: @xref{Lists}, for info on sexps.
        !          8985: 
        !          8986:   The argument to @code{find-tag} need not be the whole tag name; it can be
        !          8987: a substring of a tag name.  However, there can be many tag names containing
        !          8988: the substring you specify.  Since @code{find-tag} works by searching the
        !          8989: text of the tag table, it finds the first tag in the table that the
        !          8990: specified substring appears in.
        !          8991: 
        !          8992:   The way to find other tags that match the substring is to give
        !          8993: @code{find-tag} a numeric argument, as in @kbd{C-u M-.}; this does not
        !          8994: read a tag name, but continues searching the tag table's text for
        !          8995: another tag containing the same substring last used.  If you have a real
        !          8996: @key{META} key, @kbd{M-0 M-.}@: is an easier alternative to @kbd{C-u
        !          8997: M-.}. (That is a zero in @kbd{M-0}.)
        !          8998: 
        !          8999: @kindex C-x 4 .
        !          9000: @findex find-tag-other-window
        !          9001:   Like most commands that can switch buffers, @code{find-tag} has another
        !          9002: similar command that displays the new buffer in another window.  @kbd{C-x 4
        !          9003: .}@: invokes the function @code{find-tag-other-window}.  (This key sequence
        !          9004: ends with a period.)
        !          9005: 
        !          9006:   Emacs comes with a tag table file @file{TAGS}, in the @file{src}
        !          9007: subdirectory, which includes all the Lisp libraries and all the C
        !          9008: sources of Emacs.  By specifying this file with @code{visit-tags-table}
        !          9009: and then using @kbd{M-.}@: you can quickly look at the source of any
        !          9010: Emacs function.
        !          9011: 
        !          9012: @node Tags Search, Tags Stepping, Find Tag, Tags
        !          9013: @subsection Searching and Replacing with Tag Tables
        !          9014: 
        !          9015:   The commands in this section visit and search all the files listed in the
        !          9016: selected tag table, one by one.  For these commands, the tag table serves
        !          9017: only to specify a sequence of files to search.  A related command is
        !          9018: @kbd{M-x grep} (@pxref{Compilation}).
        !          9019: 
        !          9020: @table @kbd
        !          9021: @item M-x tags-search
        !          9022: Search for the specified regexp through the files in the selected tag
        !          9023: table.
        !          9024: @item M-x tags-query-replace
        !          9025: Perform a @code{query-replace} on each file in the selected tag table.
        !          9026: @item M-,
        !          9027: Restart one of the commands above, from the current location of point
        !          9028: (@code{tags-loop-continue}).
        !          9029: @end table
        !          9030: 
        !          9031: @findex tags-search
        !          9032:   @kbd{M-x tags-search} reads a regexp using the minibuffer, then visits
        !          9033: the files of the selected tag table one by one, and searches through each
        !          9034: one for that regexp.  It displays the name of the file being searched so
        !          9035: you can follow its progress.  As soon as an occurrence is found,
        !          9036: @code{tags-search} returns.
        !          9037: 
        !          9038: @kindex M-,
        !          9039: @findex tags-loop-continue
        !          9040:   Having found one match, you probably want to find all the rest.  To find
        !          9041: one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
        !          9042: @code{tags-search}.  This searches the rest of the current buffer, followed
        !          9043: by the remaining files of the tag table.
        !          9044: 
        !          9045: @findex tags-query-replace
        !          9046:   @kbd{M-x tags-query-replace} performs a single @code{query-replace}
        !          9047: through all the files in the tag table.  It reads a string to search for
        !          9048: and a string to replace with, just like ordinary @w{@kbd{M-x query-replace}}.
        !          9049: It searches much like @kbd{M-x tags-search} but repeatedly, processing
        !          9050: matches according to your input.  @xref{Replace}, for more information on
        !          9051: @code{query-replace}.@refill
        !          9052: 
        !          9053:   It is possible to get through all the files in the tag table with a
        !          9054: single invocation of @kbd{M-x tags-query-replace}.  But since any
        !          9055: unrecognized character causes the command to exit, you may need to continue
        !          9056: where you left off.  @kbd{M-,} can be used for this.  It resumes the last
        !          9057: tags search or replace command that you did.
        !          9058: 
        !          9059:   It may have struck you that @code{tags-search} is a lot like @code{grep}.
        !          9060: You can also run @code{grep} itself as an inferior of Emacs and have Emacs
        !          9061: show you the matching lines one by one.  This works mostly the same as
        !          9062: running a compilation and having Emacs show you where the errors were.
        !          9063: @xref{Compilation}.
        !          9064: 
        !          9065: @node Tags Stepping, List Tags, Tags Search, Tags
        !          9066: @subsection Stepping Through a Tag Table
        !          9067: @findex next-file
        !          9068: 
        !          9069:   If you wish to process all the files in the selected tag table, but
        !          9070: @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} in particular are not what
        !          9071: you want, you can use @kbd{M-x next-file}.
        !          9072: 
        !          9073: @table @kbd
        !          9074: @item C-u M-x next-file
        !          9075: With a numeric argument, regardless of its value, visit the first
        !          9076: file in the tag table, and prepare to advance sequentially by files.
        !          9077: @item M-x next-file
        !          9078: Visit the next file in the selected tag table.
        !          9079: @end table
        !          9080: 
        !          9081: @node List Tags,, Tags Stepping, Tags
        !          9082: @subsection Tag Table Inquiries
        !          9083: 
        !          9084: @table @kbd
        !          9085: @item M-x list-tags
        !          9086: Display a list of the tags defined in a specific program file.
        !          9087: @item M-x tags-apropos
        !          9088: Display a list of all tags matching a specified regexp.
        !          9089: @end table
        !          9090: 
        !          9091: @findex list-tags
        !          9092:   @kbd{M-x list-tags} reads the name of one of the files described by the
        !          9093: selected tag table, and displays a list of all the tags defined in that
        !          9094: file.  The ``file name'' argument is really just a string to compare
        !          9095: against the names recorded in the tag table; it is read as a string rather
        !          9096: than as a file name.  Therefore, completion and defaulting are not
        !          9097: available, and you must enter the string the same way it appears in the tag
        !          9098: table.  Do not include a directory as part of the file name unless the file
        !          9099: name recorded in the tag table includes a directory.
        !          9100: 
        !          9101: @findex tags-apropos
        !          9102:   @kbd{M-x tags-apropos} is like @code{apropos} for tags.  It reads a regexp,
        !          9103: then finds all the tags in the selected tag table whose entries match that
        !          9104: regexp, and displays the tag names found.
        !          9105: 
        !          9106: @node Fortran,, Tags, Programs
        !          9107: @section Fortran Mode
        !          9108: @cindex Fortran mode
        !          9109: 
        !          9110:   Fortran mode provides special motion commands for Fortran statements and
        !          9111: subprograms, and indentation commands that understand Fortran conventions
        !          9112: of nesting, line numbers and continuation statements.
        !          9113: 
        !          9114:   Special commands for comments are provided because Fortran comments are
        !          9115: unlike those of other languages.
        !          9116: 
        !          9117:   Built-in abbrevs optionally save typing when you insert Fortran keywords.
        !          9118: 
        !          9119: @findex fortran-mode
        !          9120:   Use @kbd{M-x fortran-mode} to switch to this major mode.  Doing so calls
        !          9121: the value of @code{fortran-mode-hook} as a function of no arguments if
        !          9122: that variable has a value that is not @code{nil}.
        !          9123: 
        !          9124: @menu
        !          9125: * Motion: Fortran Motion.     Moving point by statements or subprograms.
        !          9126: * Indent: Fortran Indent.     Indentation commands for Fortran.
        !          9127: * Comments: Fortran Comments. Inserting and aligning comments.
        !          9128: * Columns: Fortran Columns.   Measuring columns for valid Fortran.
        !          9129: * Abbrev: Fortran Abbrev.     Built-in abbrevs for Fortran keywords.
        !          9130: @end menu
        !          9131: 
        !          9132:   Fortran mode was contributed by Michael Prange.
        !          9133: 
        !          9134: @node Fortran Motion, Fortran Indent, Fortran, Fortran
        !          9135: @subsection Motion Commands
        !          9136: 
        !          9137:   Fortran mode provides special commands to move by subprograms (functions
        !          9138: and subroutines) and by statements.  There is also a command to put the
        !          9139: region around one subprogram, convenient for killing it or moving it.
        !          9140: 
        !          9141: @kindex C-M-a (Fortran mode)
        !          9142: @kindex C-M-e (Fortran mode)
        !          9143: @kindex C-M-h (Fortran mode)
        !          9144: @kindex C-c C-p (Fortran mode)
        !          9145: @kindex C-c C-n (Fortran mode)
        !          9146: @findex beginning-of-fortran-subprogram
        !          9147: @findex end-of-fortran-subprogram
        !          9148: @findex mark-fortran-subprogram
        !          9149: @findex fortran-previous-statement
        !          9150: @findex fortran-next-statement
        !          9151: 
        !          9152: @table @kbd
        !          9153: @c !!! following generates acceptable underfull hbox
        !          9154: @item C-M-a
        !          9155: Move to beginning of subprogram
        !          9156: (@code{beginning-of-fortran-subprogram}).
        !          9157: @item C-M-e
        !          9158: Move to end of subprogram (@code{end-of-fortran-subprogram}).
        !          9159: @item C-M-h
        !          9160: Put point at beginning of subprogram and mark at end
        !          9161: (@code{mark-fortran-subprogram}).
        !          9162: @item C-c C-n
        !          9163: Move to beginning of current or next statement
        !          9164: (@code{fortran-next-statement}).
        !          9165: @item C-c C-p
        !          9166: Move to beginning of current or previous statement
        !          9167: (@code{fortran-previous-statement}).
        !          9168: @end table
        !          9169: 
        !          9170: @node Fortran Indent, Fortran Comments, Fortran Motion, Fortran
        !          9171: @subsection Fortran Indentation
        !          9172: 
        !          9173:   Special commands and features are needed for indenting Fortran code in
        !          9174: order to make sure various syntactic entities (line numbers, comment line
        !          9175: indicators and continuation line flags) appear in the columns that are
        !          9176: required for standard Fortran.
        !          9177: 
        !          9178: @menu
        !          9179: * Commands: ForIndent Commands. Commands for indenting Fortran.
        !          9180: * Numbers:  ForIndent Num.      How line numbers auto-indent.
        !          9181: * Conv:     ForIndent Conv.     Conventions you must obey to avoid trouble.
        !          9182: * Vars:     ForIndent Vars.     Variables controlling Fortran indent style.
        !          9183: @end menu
        !          9184: 
        !          9185: @node ForIndent Commands, ForIndent Num, Fortran Indent, Fortran Indent
        !          9186: @subsubsection Fortran Indentation Commands
        !          9187: 
        !          9188: @table @kbd
        !          9189: @item @key{TAB}
        !          9190: Indent the current line (@code{fortran-indent-line}).
        !          9191: @item M-@key{LFD}
        !          9192: Break the current line and set up a continuation line.
        !          9193: @item C-M-q
        !          9194: Indent all the lines of the subprogram point is in
        !          9195: (@code{fortran-indent-subprogram}).
        !          9196: @end table
        !          9197: 
        !          9198: @findex fortran-indent-line
        !          9199:   @key{TAB} is redefined by Fortran mode to reindent the current line for
        !          9200: Fortran (@code{fortran-indent-line}).  Line numbers and continuation
        !          9201: markers are indented to their required columns, and the body of the
        !          9202: statement is independently indented based on its nesting in the program.
        !          9203: 
        !          9204: @kindex C-M-q (Fortran mode)
        !          9205: @findex fortran-indent-subprogram
        !          9206:   The key @kbd{C-M-q} is redefined as @code{fortran-indent-subprogram}, a
        !          9207: command to reindent all the lines of the Fortran subprogram (function or
        !          9208: subroutine) containing point.
        !          9209: 
        !          9210: @kindex M-LFD (Fortran mode)
        !          9211: @findex fortran-split-line
        !          9212:   The key @kbd{M-@key{LFD}} is redefined as @code{fortran-split-line}, a
        !          9213: command to split a line in the appropriate fashion for Fortran.  In a
        !          9214: non-comment line, the second half becomes a continuation line and is
        !          9215: indented accordingly.  In a comment line, both halves become separate
        !          9216: comment lines.
        !          9217: 
        !          9218: @node ForIndent Num, ForIndent Conv, ForIndent Commands, Fortran Indent
        !          9219: @subsubsection Line Numbers and Continuation
        !          9220: 
        !          9221:   If a number is the first non-whitespace in the line, it is assumed to be
        !          9222: a line number and is moved to columns 0 through 4.  (Columns are always
        !          9223: counted from 0 in GNU Emacs.)  If the text on the line starts with the
        !          9224: conventional Fortran continuation marker @samp{$}, it is moved to column 5.
        !          9225: If the text begins with any non whitespace character in column 5, it is
        !          9226: assumed to be an unconventional continuation marker and remains in column
        !          9227: 5.
        !          9228: 
        !          9229: @vindex fortran-line-number-indent
        !          9230:   Line numbers of four digits or less are normally indented one space.
        !          9231: This amount is controlled by the variable @code{fortran-line-number-indent}
        !          9232: which is the maximum indentation a line number can have.  Line numbers
        !          9233: are indented to right-justify them to end in column 4 unless that would
        !          9234: require more than this maximum indentation.  The default value of the
        !          9235: variable is 1.
        !          9236: 
        !          9237: @vindex fortran-electric-line-number
        !          9238:   Simply inserting a line number is enough to indent it according to these
        !          9239: rules.  As each digit is inserted, the indentation is recomputed.  To turn
        !          9240: off this feature, set the variable @code{fortran-electric-line-number} to
        !          9241: @code{nil}.  Then inserting line numbers is like inserting anything else.
        !          9242: 
        !          9243: @node ForIndent Conv, ForIndent Vars, ForIndent Num, Fortran Indent
        !          9244: @subsubsection Syntactic Conventions
        !          9245: 
        !          9246:   Fortran mode assumes that you follow certain conventions that simplify
        !          9247: the task of understanding a Fortran program well enough to indent it
        !          9248: properly:
        !          9249: 
        !          9250: @vindex fortran-continuation-char
        !          9251: @itemize @bullet
        !          9252: @item
        !          9253: Two nested @samp{do} loops never share a @samp{continue} statement.
        !          9254: 
        !          9255: @item
        !          9256: The same character appears in column 5 of all continuation lines, and
        !          9257: this character is the value of the variable @code{fortran-continuation-char}.
        !          9258: By default, this character is @samp{$}.
        !          9259: @end itemize
        !          9260: 
        !          9261: @noindent
        !          9262: If you fail to follow these conventions, the indentation commands may
        !          9263: indent some lines unaesthetically.  However, a correct Fortran program will
        !          9264: retain its meaning when reindented even if the conventions are not
        !          9265: followed.
        !          9266: 
        !          9267: @node ForIndent Vars,, ForIndent Conv, Fortran Indent
        !          9268: @subsubsection Variables for Fortran Indentation
        !          9269: 
        !          9270: @vindex fortran-do-indent
        !          9271: @vindex fortran-if-indent
        !          9272: @vindex fortran-continuation-indent
        !          9273: @vindex fortran-check-all-num-for-matching-do
        !          9274: @vindex fortran-minimum-statement-indent
        !          9275:   Several additional variables control how Fortran indentation works.
        !          9276: 
        !          9277: @table @code
        !          9278: @item fortran-do-indent
        !          9279: Extra indentation within each level of @samp{do} statement @*(default 3).
        !          9280: 
        !          9281: @item fortran-if-indent
        !          9282: Extra indentation within each level of @samp{if} statement @*(default 3).
        !          9283: 
        !          9284: @item fortran-continuation-indent
        !          9285: Extra indentation for bodies of continuation lines (default 5).
        !          9286: 
        !          9287: @item fortran-check-all-num-for-matching-do
        !          9288: If this is @code{nil}, indentation assumes that each @samp{do}
        !          9289: statement ends on a @samp{continue} statement.  Therefore, when
        !          9290: computing indentation for a statement other than @samp{continue}, it
        !          9291: can save time by not checking for a @samp{do} statement ending there.
        !          9292: If this is non-@code{nil}, indenting any numbered statement must check
        !          9293: for a @samp{do} that ends there.  The default is @code{nil}.
        !          9294: 
        !          9295: @item fortran-minimum-statement-indent
        !          9296: Minimum indentation for fortran statements.  For standard Fortran,
        !          9297: this is 6.  Statement bodies will never be indented less than this
        !          9298: much.
        !          9299: @end table
        !          9300: 
        !          9301: @node Fortran Comments, Fortran Columns, Fortran Indent, Fortran
        !          9302: @subsection Comments
        !          9303: 
        !          9304:   The usual Emacs comment commands assume that a comment can follow a line
        !          9305: of code.  In Fortran, the standard comment syntax requires an entire line
        !          9306: to be just a comment.  Therefore, Fortran mode replaces the standard Emacs
        !          9307: comment commands and defines some new variables.
        !          9308: 
        !          9309:   Fortran mode can also handle a nonstandard comment syntax where comments
        !          9310: start with @samp{!} and can follow other text.  Because only some Fortran
        !          9311: compilers accept this syntax, Fortran mode will not insert such comments
        !          9312: unless you have said in advance to do so.  To do this, set the variable
        !          9313: @code{comment-start} to @samp{"!"} (@pxref{Variables}).
        !          9314: 
        !          9315: @table @kbd
        !          9316: @item M-;
        !          9317: Align comment or insert new comment (@code{fortran-comment-indent}).
        !          9318: 
        !          9319: @item C-x ;
        !          9320: Applies to nonstandard @samp{!} comments only.
        !          9321: 
        !          9322: @item C-c ;
        !          9323: Turn all lines of the region into comments, or (with arg)
        !          9324: turn them back into real code (@code{fortran-comment-region}).
        !          9325: @end table
        !          9326: 
        !          9327:   @kbd{M-;} in Fortran mode is redefined as the command
        !          9328: @code{fortran-comment-indent}.  Like the usual @kbd{M-;} command, this
        !          9329: recognizes any kind of existing comment and aligns its text appropriately;
        !          9330: if there is no existing comment, a comment is inserted and aligned.  But
        !          9331: inserting and aligning comments are not the same in Fortran mode as in
        !          9332: other modes.
        !          9333: 
        !          9334:   When a new comment must be inserted, if the current line is blank, a
        !          9335: full-line comment is inserted.  On a non-blank line, a nonstandard @samp{!}
        !          9336: comment is inserted if you have said you want to use them.  Otherwise a
        !          9337: full-line comment is inserted on a new line before the current line.
        !          9338: 
        !          9339:   Nonstandard @samp{!} comments are aligned like comments in other
        !          9340: languages, but full-line comments are different.  In a standard full-line
        !          9341: comment, the comment delimiter itself must always appear in column zero.
        !          9342: What can be aligned is the text within the comment.  You can choose from
        !          9343: three styles of alignment by setting the variable
        !          9344: @code{fortran-comment-indent-style} to one of these values:
        !          9345: 
        !          9346: @vindex fortran-comment-indent-style
        !          9347: @vindex fortran-comment-line-column
        !          9348: @table @code
        !          9349: @item fixed
        !          9350: The text is aligned at a fixed column, which is the value of
        !          9351: @code{fortran-comment-line-column}.  This is the default.
        !          9352: @item relative
        !          9353: The text is aligned as if it were a line of code, but with an
        !          9354: additional @code{fortran-comment-line-column} columns of indentation.
        !          9355: @item nil
        !          9356: Text in full-line columns is not moved automatically.
        !          9357: @end table
        !          9358: 
        !          9359: @vindex fortran-comment-indent-char
        !          9360:   In addition, you can specify the character to be used to indent within
        !          9361: full-line comments by setting the variable @code{fortran-comment-indent-char}
        !          9362: to the character you want to use.
        !          9363: 
        !          9364: @vindex comment-line-start
        !          9365: @vindex comment-line-start-skip
        !          9366:   Fortran mode introduces the two variables, @code{comment-line-start} and
        !          9367: @code{comment-line-start-skip}, which play for full-line comments the same
        !          9368: roles played by @code{comment-start} and @code{comment-start-skip} for
        !          9369: ordinary text-following comments.  Normally these are set properly by
        !          9370: Fortran mode so you do not need to change them.
        !          9371: 
        !          9372:   The normal Emacs comment command @kbd{C-x ;} has not been redefined.
        !          9373: If you use @samp{!} comments, this command can be used with them.  Otherwise
        !          9374: it is useless in Fortran mode.
        !          9375: 
        !          9376: @kindex C-c ; (Fortran mode)
        !          9377: @findex fortran-comment-region
        !          9378: @vindex fortran-comment-region
        !          9379:   The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the
        !          9380: lines of the region into comments by inserting the string @samp{C$$$} at
        !          9381: the front of each one.  With a numeric arg, the region is turned back into
        !          9382: live code by deleting @samp{C$$$} from the front of each line in it.  The
        !          9383: string used for these comments can be controlled by setting the variable
        !          9384: @code{fortran-comment-region}.  Note that here we have an example of a
        !          9385: command and a variable with the same name; these two uses of the name never
        !          9386: conflict because in Lisp and in Emacs it is always clear from the context
        !          9387: which one is meant.
        !          9388: 
        !          9389: @node Fortran Columns, Fortran Abbrev, Fortran Comments, Fortran
        !          9390: @subsection Columns
        !          9391: 
        !          9392: @table @kbd
        !          9393: @item C-c C-r
        !          9394: Displays a ``column ruler'' momentarily above the current line
        !          9395: (@code{fortran-column-ruler}).
        !          9396: @item C-c C-w
        !          9397: Splits the current window horizontally so that it is 72 columns wide.
        !          9398: This may help you avoid going over that limit (@code{fortran-window-create}).
        !          9399: @end table
        !          9400: 
        !          9401: @kindex C-c C-r (Fortran mode)
        !          9402: @findex fortran-column-ruler
        !          9403: @vindex fortran-column-ruler
        !          9404:   The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column
        !          9405: ruler momentarily above the current line.  The comment ruler is two lines
        !          9406: of text that show you the locations of columns with special significance
        !          9407: in Fortran programs.  Square brackets show the limits of the columns for
        !          9408: line numbers, and curly brackets show the limits of the columns for the
        !          9409: statement body.  Column numbers appear above them.
        !          9410: 
        !          9411:   Note that the column numbers count from zero, as always in GNU Emacs.  As
        !          9412: a result, the numbers may not be those you are familiar with; but the
        !          9413: actual positions in the line are standard Fortran.
        !          9414: 
        !          9415:   The text used to display the column ruler is the value of the variable
        !          9416: @code{fortran-comment-ruler}.  By changing this variable, you can change
        !          9417: the display.
        !          9418: 
        !          9419: @kindex C-c C-w (Fortran mode)
        !          9420: @findex fortran-window-create
        !          9421:   For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a
        !          9422: command which splits the current window horizontally, making a window 72
        !          9423: columns wide.  By editing in this window you can immediately see when you
        !          9424: make a line too wide to be correct Fortran.
        !          9425: 
        !          9426: @node Fortran Abbrev,, Fortran Columns, Fortran
        !          9427: @subsection Fortran Keyword Abbrevs
        !          9428: 
        !          9429:   Fortran mode provides many built-in abbrevs for common keywords and
        !          9430: declarations.  These are the same sort of abbrev that you can define
        !          9431: yourself.  To use them, you must turn on Abbrev mode (@pxref{Abbrevs}).
        !          9432: 
        !          9433:   The built-in abbrevs are unusual in one way: they all start with a
        !          9434: semicolon.  You cannot normally use semicolons in an abbrev, but Fortran
        !          9435: mode makes this possible by changing the syntax of semicolon to ``word
        !          9436: constituent''.
        !          9437: 
        !          9438:   For example, one built-in Fortran abbrev is @samp{;c} for
        !          9439: @samp{continue}.  If you insert @samp{;c} and then insert a punctuation
        !          9440: character such as a space or a newline, the @samp{;c} will change
        !          9441: automatically to @samp{continue}, provided Abbrev mode is enabled.@refill
        !          9442: 
        !          9443:   Type @samp{;?} or @samp{;C-h} to display a list of all the built-in
        !          9444: Fortran abbrevs and what they stand for.
        !          9445: 
        !          9446: @node Compiling/Testing, Abbrevs, Programs, Top
        !          9447: @chapter Compiling and Testing Programs
        !          9448: 
        !          9449:   The previous chapter discusses the Emacs commands that are useful for
        !          9450: making changes in programs.  This chapter deals with commands that assist
        !          9451: in the larger process of developing and maintaining programs.
        !          9452: 
        !          9453: @menu
        !          9454: * Compilation::        Compiling programs in languages other than Lisp
        !          9455:                         (C, Pascal, etc.)
        !          9456: * Modes: Lisp Modes.   Various modes for editing Lisp programs, with
        !          9457:                        different facilities for running the Lisp programs.
        !          9458: * Libraries: Lisp Libraries.      Creating Lisp programs to run in Emacs.
        !          9459: * Interaction: Lisp Interaction.  Executing Lisp in an Emacs buffer.
        !          9460: * Eval: Lisp Eval.     Executing a single Lisp expression in Emacs.
        !          9461: * Debug: Lisp Debug.   Debugging Lisp programs running in Emacs.
        !          9462: * External Lisp::      Communicating through Emacs with a separate Lisp.
        !          9463: @end menu
        !          9464: 
        !          9465: @node Compilation, Lisp Modes, Compiling/Testing, Compiling/Testing
        !          9466: @section Running `make', or Compilers Generally
        !          9467: @cindex inferior process
        !          9468: @cindex make
        !          9469: @cindex compilation errors
        !          9470: @cindex error log
        !          9471: 
        !          9472:   Emacs can run compilers for noninteractive languages such as C and
        !          9473: Fortran as inferior processes, feeding the error log into an Emacs buffer.
        !          9474: It can also parse the error messages and visit the files in which errors
        !          9475: are found, moving point right to the line where the error occurred.
        !          9476: 
        !          9477: @table @kbd
        !          9478: @item M-x compile
        !          9479: Run a compiler asynchronously under Emacs, with error messages to
        !          9480: @samp{*compilation*} buffer.
        !          9481: @item M-x grep
        !          9482: Run @code{grep} asynchronously under Emacs, with matching lines
        !          9483: listed in the buffer named @samp{*compilation*}.
        !          9484: @item M-x kill-compilation
        !          9485: @itemx M-x kill-grep
        !          9486: Kill the running compilation or @code{grep} subprocess.
        !          9487: @item C-x `
        !          9488: Visit the locus of the next compiler error message or @code{grep} match.
        !          9489: @end table
        !          9490: 
        !          9491: @findex compile
        !          9492:   To run @code{make} or another compiler, do @kbd{M-x compile}.  This command
        !          9493: reads a shell command line using the minibuffer, and then executes the
        !          9494: specified command line in an inferior shell with output going to the buffer
        !          9495: named @samp{*compilation*}.  The current buffer's default directory is used
        !          9496: as the working directory for the execution of the command; normally,
        !          9497: therefore, the makefile comes from this directory.
        !          9498: 
        !          9499: @vindex compile-command
        !          9500:   When the shell command line is read, the minibuffer appears containing a
        !          9501: default command line, which is the command you used the last time you did
        !          9502: @kbd{M-x compile}.  If you type just @key{RET}, the same command line is used
        !          9503: again.  The first @kbd{M-x compile} provides @code{make -k} as the default.
        !          9504: The default is taken from the variable @code{compile-command}; if the
        !          9505: appropriate compilation command for a file is something other than
        !          9506: @code{make -k}, it can be useful to have the file specify a local value for
        !          9507: @code{compile-command} (@pxref{File Variables}).
        !          9508: 
        !          9509:   Starting a compilation causes the buffer @samp{*compilation*} to be
        !          9510: displayed in another window but not selected.  Its mode line tells you
        !          9511: whether compilation is finished, with the word @samp{run} or @samp{exit} inside
        !          9512: the parentheses.  You do not have to keep this buffer visible; compilation
        !          9513: continues in any case.
        !          9514: 
        !          9515: @findex kill-compilation
        !          9516:   To kill the compilation process, do @kbd{M-x kill-compilation}.  You will
        !          9517: see that the mode line of the @samp{*compilation*} buffer changes to say
        !          9518: @samp{signal} instead of @samp{run}.  Starting a new compilation also kills
        !          9519: any running compilation, as only one can exist at any time.  However, this
        !          9520: requires confirmation before actually killing a compilation that is
        !          9521: running.@refill
        !          9522: 
        !          9523: @kindex C-x `
        !          9524: @findex next-error
        !          9525:   To parse the compiler error messages, type @kbd{C-x `} (@code{next-error}).  The
        !          9526: character following the @kbd{C-x} is the grave accent, not the single
        !          9527: quote.  This command displays the buffer @samp{*compilation*} in one window
        !          9528: and the buffer in which the next error occurred in another window.  Point
        !          9529: in that buffer is moved to the line where the error was found.  The
        !          9530: corresponding error message is scrolled to the top of the window in which
        !          9531: @samp{*compilation*} is displayed.
        !          9532: 
        !          9533:   The first time @kbd{C-x `} is used after the start of a compilation, it
        !          9534: parses all the error messages, visits all the files that have error
        !          9535: messages, and makes markers pointing at the lines that the error messages
        !          9536: refer to.  Then it moves to the first error message location.  Subsequent
        !          9537: uses of @kbd{C-x `} advance down the data set up by the first use.  When
        !          9538: the preparsed error messages are exhausted, the next @kbd{C-x `} checks for
        !          9539: any more error messages that have come in; this is useful if you start
        !          9540: editing the compiler errors while the compilation is still going on.  If no
        !          9541: more error messages have come in, @kbd{C-x `} reports an error.
        !          9542: 
        !          9543:   @kbd{C-u C-x `} discards the preparsed error message data and parses the
        !          9544: @samp{*compilation*} buffer over again, then displaying the first error.
        !          9545: This way, you can process the same set of errors again.
        !          9546: 
        !          9547: @findex grep
        !          9548:   Instead of running a compiler, you can run @code{grep} and see the lines
        !          9549: on which matches were found.  To do this, type @kbd{M-x grep} with an argument
        !          9550: line that contains the same arguments you would give @code{grep} when running
        !          9551: it normally: a @code{grep}-style regexp (usually in singlequotes to quote
        !          9552: the shell's special characters) followed by filenames which may use wildcards.
        !          9553: The output from @code{grep} goes in the @samp{*compilation*} buffer and the
        !          9554: lines that matched can be found with @kbd{C-x `} as if they were compilation
        !          9555: errors.
        !          9556: 
        !          9557:   Note: a shell is used to run the compile command, but the shell is told
        !          9558: that it should be noninteractive.  This means in particular that the shell
        !          9559: starts up with no prompt.  If you find your usual shell prompt making an
        !          9560: unsightly appearance in the @samp{*compilation*} buffer, it means you have
        !          9561: made a mistake in your shell's init file (@file{.cshrc} or @file{.shrc} or
        !          9562: @dots{}) by setting the prompt unconditionally.  The shell init file should
        !          9563: set the prompt only if there already is a prompt.  
        !          9564: 
        !          9565: Here is how to do it in @code{csh}:
        !          9566: 
        !          9567: @example
        !          9568: if ($?prompt) set prompt = ...
        !          9569: @end example
        !          9570: 
        !          9571: Here is how to do it in the Bourne-Again shell:
        !          9572: 
        !          9573: @example
        !          9574: @group
        !          9575: if [ ! "$PS1" ]; then
        !          9576:    PS1=@dots{}
        !          9577: fi
        !          9578: @end group
        !          9579: @end example
        !          9580: 
        !          9581: @node Lisp Modes, Lisp Libraries, Compilation, Compiling/Testing
        !          9582: @section Major Modes for Lisp
        !          9583: 
        !          9584: @cindex Lisp mode
        !          9585: @cindex Scheme mode
        !          9586: @cindex Inferior Scheme mode
        !          9587:   Emacs has four different major modes for Lisp.  They are the same in
        !          9588: terms of editing commands, but differ in the commands for executing Lisp
        !          9589: expressions.
        !          9590: 
        !          9591: @table @asis
        !          9592: @item Emacs-Lisp mode
        !          9593: The mode for editing source files of programs to run in Emacs Lisp.
        !          9594: This mode defines @kbd{C-M-x} to evaluate the current defun.
        !          9595: @xref{Lisp Libraries}.
        !          9596: @item Lisp Interaction mode
        !          9597: The mode for an interactive session with Emacs Lisp.  It defines
        !          9598: @key{LFD} to evaluate the sexp before point and insert its value in the
        !          9599: buffer.  @xref{Lisp Interaction}.
        !          9600: @item Lisp mode
        !          9601: The mode for editing source files of programs that run in Lisps other
        !          9602: than Emacs Lisp.  This mode defines @kbd{C-M-x} to send the current defun
        !          9603: to an inferior Lisp process.  @xref{External Lisp}.
        !          9604: @item Inferior Lisp mode
        !          9605: The mode for an interactive session with an inferior Lisp process.
        !          9606: This mode combines the special features of Lisp mode and Shell mode
        !          9607: (@pxref{Shell Mode}).
        !          9608: @item Scheme mode
        !          9609: Like Lisp mode but for Scheme programs.
        !          9610: @item Inferior Scheme mode
        !          9611: The mode for an interactive session with an inferior Scheme process.
        !          9612: @end table
        !          9613: 
        !          9614: @node Lisp Libraries, Lisp Eval, Lisp Modes, Compiling/Testing
        !          9615: @section Libraries of Lisp Code for Emacs
        !          9616: @cindex libraries
        !          9617: @cindex loading Lisp code
        !          9618: 
        !          9619:   Lisp code for Emacs editing commands is stored in files whose names
        !          9620: conventionally end in @file{.el}.  This ending tells Emacs to edit them in
        !          9621: Emacs-Lisp mode (@pxref{Lisp Modes}).
        !          9622: 
        !          9623: @menu
        !          9624: * Loading::            Loading libraries of Lisp code into Emacs for use.
        !          9625: * Compiling Libraries:: Compiling a library makes it load and run faster.
        !          9626: * Mocklisp::           Converting Mocklisp to Lisp so GNU Emacs can run it.
        !          9627: @end menu
        !          9628: 
        !          9629: @node Loading, Compiling Libraries, Lisp Libraries, Lisp Libraries
        !          9630: @subsection Loading Libraries
        !          9631: 
        !          9632: @findex load-file
        !          9633:   To execute a file of Emacs Lisp, use @kbd{M-x load-file}.  This command
        !          9634: reads a file name using the minibuffer and then executes the contents of
        !          9635: that file as Lisp code.  It is not necessary to visit the file first;
        !          9636: in any case, this command reads the file as found on disk, not text in
        !          9637: an Emacs buffer.
        !          9638: 
        !          9639: @findex load
        !          9640: @findex load-library
        !          9641:   Once a file of Lisp code is installed in the Emacs Lisp library
        !          9642: directories, users can load it using @kbd{M-x load-library}.  Programs can
        !          9643: load it by calling @code{load-library}, or with @code{load}, a more primitive
        !          9644: function that is similar but accepts some additional arguments.
        !          9645: 
        !          9646:   @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it
        !          9647: searches a sequence of directories and tries three file names in each
        !          9648: directory.  The three names are, first, the specified name with @file{.elc}
        !          9649: appended; second, with @file{.el} appended; third, the specified
        !          9650: name alone.  A @file{.elc} file would be the result of compiling the Lisp
        !          9651: file into byte code; it is loaded if possible in preference to the Lisp
        !          9652: file itself because the compiled file will load and run faster.
        !          9653: 
        !          9654:   Because the argument to @code{load-library} is usually not in itself
        !          9655: a valid file name, file name completion is not available.  Indeed, when
        !          9656: using this command, you usually do not know exactly what file name
        !          9657: will be used.
        !          9658: 
        !          9659: @vindex load-path
        !          9660:   The sequence of directories searched by @kbd{M-x load-library} is
        !          9661: specified by the variable @code{load-path}, a list of strings that are
        !          9662: directory names.  The default value of the list contains the directory where
        !          9663: the Lisp code for Emacs itself is stored.  If you have libraries of
        !          9664: your own, put them in a single directory and add that directory
        !          9665: to @code{load-path}.  @code{nil} in this list stands for the current default
        !          9666: directory, but it is probably not a good idea to put @code{nil} in the
        !          9667: list.  If you find yourself wishing that @code{nil} were in the list,
        !          9668: most likely what you really want to do is use @kbd{M-x load-file}
        !          9669: this once.
        !          9670: 
        !          9671: @cindex autoload
        !          9672:   Often you do not have to give any command to load a library, because the
        !          9673: commands defined in the library are set up to @dfn{autoload} that library.
        !          9674: Running any of those commands causes @code{load} to be called to load the
        !          9675: library; this replaces the autoload definitions with the real ones from the
        !          9676: library.
        !          9677: 
        !          9678:   If autoloading a file does not finish, either because of an error or
        !          9679: because of a @kbd{C-g} quit, all function definitions made by the file are
        !          9680: undone automatically.  So are any calls to @code{provide}.  As a consequence,
        !          9681: if you use one of the autoloadable commands again, the entire file will be
        !          9682: loaded a second time.  This prevents problems where the command is no
        !          9683: longer autoloading but it works wrong because not all the file was loaded.
        !          9684: Function definitions are undone only for autoloading; explicit calls to
        !          9685: @code{load} do not undo anything if loading is not completed.
        !          9686: 
        !          9687: @node Compiling Libraries, Mocklisp, Loading, Lisp Libraries
        !          9688: @subsection Compiling Libraries
        !          9689: 
        !          9690: @cindex byte code
        !          9691:   Emacs Lisp code can be compiled into byte-code which loads faster,
        !          9692: takes up less space when loaded, and executes faster.
        !          9693: 
        !          9694: @findex byte-compile-file
        !          9695:   The way to make a byte-code compiled file from an Emacs-Lisp source file
        !          9696: is with @kbd{M-x byte-compile-file}.  The default argument for this
        !          9697: function is the file visited in the current buffer.  It reads the specified
        !          9698: file, compiles it into byte code, and writes an output file whose name is
        !          9699: made by appending @file{c} to the input file name.  Thus, the file
        !          9700: @file{rmail.el} would be compiled into @file{rmail.elc}.
        !          9701: 
        !          9702: @findex byte-recompile-directory
        !          9703:   To recompile the changed Lisp files in a directory, use @kbd{M-x
        !          9704: byte-recompile-directory}.  Specify just the directory name as an argument.
        !          9705: Each @file{.el} file that has been byte-compiled before is byte-compiled
        !          9706: again if it has changed since the previous compilation.  A numeric argument
        !          9707: to this command tells it to offer to compile each @file{.el} file that has
        !          9708: not already been compiled.  You must answer @kbd{y} or @kbd{n} to each
        !          9709: offer.
        !          9710: 
        !          9711: @findex batch-byte-compile
        !          9712:   Emacs can be invoked noninteractively from the shell to do byte compilation
        !          9713: with the aid of the function @code{batch-byte-compile}.  In this case,
        !          9714: the files to be compiled are specified with command-line arguments.
        !          9715: Use a shell command of the form
        !          9716: 
        !          9717: @example
        !          9718: emacs -batch -f batch-byte-compile @var{files}...
        !          9719: @end example
        !          9720: 
        !          9721:   Directory names may also be given as arguments;
        !          9722: @code{byte-recompile-directory} is invoked (in effect) on each such directory.
        !          9723: @code{batch-byte-compile} uses all the remaining command-line arguments as
        !          9724: file or directory names, then kills the Emacs process.
        !          9725: 
        !          9726: @cindex disassemble
        !          9727: @findex disassemble
        !          9728:   @kbd{M-x disassemble} explains the result of byte compilation.  Its
        !          9729: argument is a function name.  It displays the byte-compiled code in a help
        !          9730: window in symbolic form, one instruction per line.  If the instruction
        !          9731: refers to a variable or constant, that is shown too.
        !          9732: 
        !          9733: @node Mocklisp,,Compiling Libraries,Lisp Libraries
        !          9734: @subsection Converting Mocklisp to Lisp
        !          9735: 
        !          9736: @cindex mocklisp
        !          9737: @findex convert-mocklisp-buffer
        !          9738:   GNU Emacs can run Mocklisp files by converting them to Emacs Lisp first.
        !          9739: To convert a Mocklisp file, visit it and then type @kbd{M-x
        !          9740: convert-mocklisp-buffer}.  Then save the resulting buffer of Lisp file in a
        !          9741: file whose name ends in @file{.el} and use the new file as a Lisp library.
        !          9742: 
        !          9743:   It does not currently work to byte-compile converted Mocklisp code.
        !          9744: This is because converted Mocklisp code uses some special Lisp features
        !          9745: to deal with Mocklisp's incompatible ideas of how arguments are evaluated
        !          9746: and which values signify ``true'' or ``false''.
        !          9747: 
        !          9748: @node Lisp Eval, Lisp Debug, Lisp Libraries, Compiling/Testing
        !          9749: @section Evaluating Emacs-Lisp Expressions
        !          9750: @cindex Emacs-Lisp mode
        !          9751: 
        !          9752: @findex emacs-lisp-mode
        !          9753:   Lisp programs intended to be run in Emacs should be edited in Emacs-Lisp
        !          9754: mode; this will happen automatically for file names ending in @file{.el}.
        !          9755: By contrast, Lisp mode itself is used for editing Lisp programs intended
        !          9756: for other Lisp systems.  Emacs-Lisp mode can be selected with the command
        !          9757: @kbd{M-x emacs-lisp-mode}.
        !          9758: 
        !          9759:   For testing of Lisp programs to run in Emacs, it is useful to be able to
        !          9760: evaluate part of the program as it is found in the Emacs buffer.  For
        !          9761: example, after changing the text of a Lisp function definition, evaluating
        !          9762: the definition installs the change for future calls to the function.
        !          9763: Evaluation of Lisp expressions is also useful in any kind of editing task
        !          9764: for invoking noninteractive functions (functions that are not commands).
        !          9765: 
        !          9766: @table @kbd
        !          9767: @item M-@key{ESC}
        !          9768: Read a Lisp expression in the minibuffer, evaluate it, and print the
        !          9769: value in the minibuffer (@code{eval-expression}).
        !          9770: @item C-x C-e
        !          9771: Evaluate the Lisp expression before point, and print the value in the
        !          9772: minibuffer (@code{eval-last-sexp}).
        !          9773: @item C-M-x
        !          9774: Evaluate the defun containing or after point, and print the value in
        !          9775: the minibuffer (@code{eval-defun}).
        !          9776: @item M-x eval-region
        !          9777: Evaluate all the Lisp expressions in the region.
        !          9778: @item M-x eval-current-buffer
        !          9779: Evaluate all the Lisp expressions in the buffer.
        !          9780: @end table
        !          9781: 
        !          9782: @kindex M-ESC
        !          9783: @findex eval-expression
        !          9784:   @kbd{M-@key{ESC}} (@code{eval-expression}) is the most basic command for evaluating
        !          9785: a Lisp expression interactively.  It reads the expression using the
        !          9786: minibuffer, so you can execute any expression on a buffer regardless of
        !          9787: what the buffer contains.  When the expression is evaluated, the current
        !          9788: buffer is once again the buffer that was current when @kbd{M-@key{ESC}} was
        !          9789: typed.
        !          9790: 
        !          9791:   @kbd{M-@key{ESC}} can easily confuse users who do not understand it,
        !          9792: especially on keyboards with autorepeat where it can result from holding
        !          9793: down the @key{ESC} key for too long.  Therefore, @code{eval-expression} is
        !          9794: normally a disabled command.  Attempting to use this command asks for
        !          9795: confirmation and gives you the option of enabling it; once you enable the
        !          9796: command, confirmation will no longer be required for it.
        !          9797: @xref{Disabling}.@refill
        !          9798: 
        !          9799: @kindex C-M-x
        !          9800: @findex eval-defun
        !          9801:   In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the function @code{eval-defun},
        !          9802: which parses the defun containing or following point as a Lisp expression
        !          9803: and evaluates it.  The value is printed in the echo area.  This command is
        !          9804: convenient for installing in the Lisp environment changes that you have
        !          9805: just made in the text of a function definition.
        !          9806: 
        !          9807: @kindex C-x C-e
        !          9808: @findex eval-last-sexp
        !          9809:   The command @kbd{C-x C-e} (@code{eval-last-sexp}) performs a similar job
        !          9810: but is available in all major modes, not just Emacs-Lisp mode.  It finds
        !          9811: the sexp before point, reads it as a Lisp expression, evaluates it, and
        !          9812: prints the value in the echo area.  It is sometimes useful to type in an
        !          9813: expression and then, with point still after it, type @kbd{C-x C-e}.
        !          9814: 
        !          9815:   If @kbd{C-M-x} or @kbd{C-x C-e} is given a numeric argument, it prints the value
        !          9816: by insertion into the current buffer at point, rather than in the echo
        !          9817: area.  The argument value does not matter.
        !          9818: 
        !          9819: @findex eval-region
        !          9820: @findex eval-current-buffer
        !          9821:   The most general command for evaluating Lisp expressions from a buffer is
        !          9822: @code{eval-region}.  @kbd{M-x eval-region} parses the text of the region as one or
        !          9823: more Lisp expressions, evaluating them one by one.  @kbd{M-x eval-current-buffer}
        !          9824: is similar but evaluates the entire buffer.  This is a reasonable way to
        !          9825: install the contents of a file of Lisp code that you are just ready to
        !          9826: test.  After finding and fixing a bug, use @kbd{C-M-x} on each function
        !          9827: that you change, to keep the Lisp world in step with the source file.
        !          9828: 
        !          9829: @node Lisp Debug, Lisp Interaction, Lisp Eval, Compiling/Testing
        !          9830: @section The Emacs-Lisp Debugger
        !          9831: @cindex debugger
        !          9832: 
        !          9833: @vindex debug-on-error
        !          9834: @vindex debug-on-quit
        !          9835:   GNU Emacs contains a debugger for Lisp programs executing inside it.
        !          9836: This debugger is normally not used; many commands frequently get Lisp
        !          9837: errors when invoked in inappropriate contexts (such as @kbd{C-f} at the end
        !          9838: of the buffer) and it would be very unpleasant for that to enter a special
        !          9839: debugging mode.  When you want to make Lisp errors invoke the debugger, you
        !          9840: must set the variable @code{debug-on-error} to non-@code{nil}.  Quitting
        !          9841: with @kbd{C-g} is not considered an error, and @code{debug-on-error} has no
        !          9842: effect on the handling of @kbd{C-g}.  However, if you set
        !          9843: @code{debug-on-quit} non-@code{nil}, @kbd{C-g} will invoke the debugger.
        !          9844: This can be useful for debugging an infinite loop; type @kbd{C-g} once the
        !          9845: loop has had time to reach its steady state.  @code{debug-on-quit} has no
        !          9846: effect on errors.@refill
        !          9847: 
        !          9848: @findex debug-on-entry
        !          9849: @findex cancel-debug-on-entry
        !          9850: @findex debug
        !          9851:   You can also cause the debugger to be entered when a specified function
        !          9852: is called, or at a particular place in Lisp code.  Use @kbd{M-x
        !          9853: debug-on-entry} with argument @var{fun-name} to cause function
        !          9854: @var{fun-name} to enter the debugger as soon as it is called.  Use
        !          9855: @kbd{M-x cancel-debug-on-entry} to make the function stop entering the
        !          9856: debugger when called.  (Redefining the function also does this.)  To enter
        !          9857: the debugger from some other place in Lisp code, you must insert the
        !          9858: expression @code{(debug)} there and install the changed code with
        !          9859: @kbd{C-M-x}.  @xref{Lisp Eval}.@refill
        !          9860: 
        !          9861:   When the debugger is entered, it displays the previously selected buffer
        !          9862: in one window and a buffer named @samp{*Backtrace*} in another window.  The
        !          9863: backtrace buffer contains one line for each level of Lisp function
        !          9864: execution currently going on.  At the beginning of this buffer is a message
        !          9865: describing the reason that the debugger was invoked (such as, what error
        !          9866: message if it was invoked due to an error).
        !          9867: 
        !          9868: @cindex Backtrace mode
        !          9869:   The backtrace buffer is read-only, and is in a special major mode,
        !          9870: Backtrace mode, in which letters are defined as debugger commands.  The
        !          9871: usual Emacs editing commands are available; you can switch windows to
        !          9872: examine the buffer that was being edited at the time of the error, and you
        !          9873: can also switch buffers, visit files, and do any other sort of editing.
        !          9874: However, the debugger is a recursive editing level (@pxref{Recursive Edit})
        !          9875: and it is wise to go back to the backtrace buffer and exit the debugger
        !          9876: officially when you don't want to use it any more.  Exiting the debugger
        !          9877: kills the backtrace buffer.
        !          9878: 
        !          9879: @cindex current stack frame
        !          9880:   The contents of the backtrace buffer show you the functions that are
        !          9881: executing and the arguments that were given to them.  It has the additional
        !          9882: purpose of allowing you to specify a stack frame by moving point to the line
        !          9883: describing that frame.  The frame whose line point is on is considered the
        !          9884: @dfn{current frame}.  Some of the debugger commands operate on the current
        !          9885: frame.  Debugger commands are mainly used for stepping through code an
        !          9886: expression at a time.  Here is a list of them.
        !          9887: 
        !          9888: @table @kbd
        !          9889: @item c
        !          9890: Exit the debugger and continue execution.  In most cases, execution of
        !          9891: the program continues as if the debugger had never been entered (aside
        !          9892: from the effect of any variables or data structures you may have
        !          9893: changed while inside the debugger).  This includes entry to the
        !          9894: debugger due to function entry or exit, explicit invocation, quitting
        !          9895: or certain errors.  Most errors cannot be continued; trying to
        !          9896: continue one of them causes the same error to occur again.
        !          9897: @item d
        !          9898: Continue execution, but enter the debugger the next time a Lisp
        !          9899: function is called.  This allows you to step through the
        !          9900: subexpressions of an expression, seeing what values the subexpressions
        !          9901: compute and what else they do.
        !          9902: 
        !          9903: The stack frame made for the function call which enters the debugger
        !          9904: in this way will be flagged automatically for the debugger to be called
        !          9905: when the frame is exited.  You can use the @kbd{u} command to cancel
        !          9906: this flag.
        !          9907: @item b
        !          9908: Set up to enter the debugger when the current frame is exited.  Frames
        !          9909: that will invoke the debugger on exit are flagged with stars.
        !          9910: @item u
        !          9911: Don't enter the debugger when the current frame is exited.  This
        !          9912: cancels a @kbd{b} command on that frame.
        !          9913: @item e
        !          9914: Read a Lisp expression in the minibuffer, evaluate it, and print the
        !          9915: value in the echo area.  This is the same as the command @kbd{M-@key{ESC}},
        !          9916: except that @kbd{e} is not normally disabled like @kbd{M-@key{ESC}}.
        !          9917: @item q
        !          9918: Terminate the program being debugged; return to top-level Emacs
        !          9919: command execution.
        !          9920: 
        !          9921: If the debugger was entered due to a @kbd{C-g} but you really want
        !          9922: to quit, not to debug, use the @kbd{q} command.
        !          9923: @item r
        !          9924: Return a value from the debugger.  The value is computed by reading an
        !          9925: expression with the minibuffer and evaluating it.
        !          9926: 
        !          9927: The value returned by the debugger makes a difference when the debugger
        !          9928: was invoked due to exit from a Lisp call frame (as requested with @kbd{b});
        !          9929: then the value specified in the @kbd{r} command is used as the value of
        !          9930: that frame.
        !          9931: 
        !          9932: The debugger's return value also matters with many errors.  For example,
        !          9933: @code{wrong-type-argument} errors will use the debugger's return value
        !          9934: instead of the invalid argument; @code{no-catch} errors will use the
        !          9935: debugger value as a throw tag instead of the tag that was not found.
        !          9936: If an error was signaled by calling the Lisp function @code{signal},
        !          9937: the debugger's return value is returned as the value of @code{signal}.
        !          9938: @end table
        !          9939: 
        !          9940: @node Lisp Interaction, External Lisp, Lisp Debug, Compiling/Testing
        !          9941: @section Lisp Interaction Buffers
        !          9942: 
        !          9943: @cindex Lisp Interaction mode
        !          9944: @cindex scratch buffer
        !          9945:   The buffer @samp{*scratch*} which is selected when Emacs starts up is
        !          9946: provided for evaluating Lisp expressions interactively inside Emacs.  Both
        !          9947: the expressions you evaluate and their output goes in the buffer.
        !          9948: 
        !          9949:   The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which
        !          9950: is the same as Emacs-Lisp mode except for one command, @key{LFD}.  In
        !          9951: Emacs-Lisp mode, @key{LFD} is an indentation command, as usual.  In Lisp
        !          9952: Interaction mode, @key{LFD} is bound to @code{eval-print-last-sexp}.  This
        !          9953: function reads the Lisp expression before point, evaluates it, and inserts
        !          9954: the value in printed representation before point.
        !          9955: 
        !          9956:   Thus, the way to use the @samp{*scratch*} buffer is to insert Lisp expressions
        !          9957: at the end, ending each one with @key{LFD} so that it will be evaluated.
        !          9958: The result is a complete typescript of the expressions you have evaluated
        !          9959: and their values.
        !          9960: 
        !          9961: @findex lisp-interaction-mode
        !          9962:   The rationale for this feature is that Emacs must have a buffer when it
        !          9963: starts up, but that buffer is not useful for editing files since a new
        !          9964: buffer is made for every file that you visit.  The Lisp interpreter
        !          9965: typescript is the most useful thing I can think of for the initial buffer
        !          9966: to do.  @kbd{M-x lisp-interaction-mode} will put any buffer in Lisp
        !          9967: Interaction mode.
        !          9968: 
        !          9969: @node External Lisp,, Lisp Interaction, Compiling/Testing
        !          9970: @section Running an External Lisp
        !          9971: 
        !          9972:   Emacs has facilities for running programs in other Lisp systems.  You can
        !          9973: run a Lisp process as an inferior of Emacs, and pass expressions to it to
        !          9974: be evaluated.  You can also pass changed function definitions directly from
        !          9975: the Emacs buffers in which you edit the Lisp programs to the inferior Lisp
        !          9976: process.
        !          9977: 
        !          9978: @findex run-lisp
        !          9979: @cindex Inferior Lisp mode
        !          9980:   To run an inferior Lisp process, type @kbd{M-x run-lisp}.  This runs the
        !          9981: program named @code{lisp}, the same program you would run by typing
        !          9982: @code{lisp} as a shell command, with both input and output going through an
        !          9983: Emacs buffer named @samp{*lisp*}.  That is to say, any ``terminal output''
        !          9984: from Lisp will go into the buffer, advancing point, and any ``terminal
        !          9985: input'' for Lisp comes from text in the buffer.  To give input to Lisp, go
        !          9986: to the end of the buffer and type the input, terminated by @key{RET}.  The
        !          9987: @samp{*lisp*} buffer is in Inferior Lisp mode, a mode which has all the
        !          9988: special characteristics of Lisp mode and Shell mode (@pxref{Shell Mode}).
        !          9989: 
        !          9990: @findex lisp-mode
        !          9991:   For the source files of programs to run in external Lisps, use Lisp mode.
        !          9992: This mode can be selected with @kbd{M-x lisp-mode}, and is used automatically
        !          9993: for files whose names end in @file{.l} or @file{.lisp}, as most Lisp
        !          9994: systems usually expect.
        !          9995: 
        !          9996: @kindex C-M-x
        !          9997: @findex lisp-send-defun
        !          9998:   When you edit a function in a Lisp program you are running, the easiest
        !          9999: way to send the changed definition to the inferior Lisp process is the key
        !          10000: @kbd{C-M-x}.  In Lisp mode, this runs the function @code{lisp-send-defun},
        !          10001: which finds the defun around or following point and sends it as input to
        !          10002: the Lisp process.  (Emacs can send input to any inferior process regardless
        !          10003: of what buffer is current.)
        !          10004: 
        !          10005:   Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs
        !          10006: to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp
        !          10007: programs to be run in Emacs): in both modes it has the effect of installing
        !          10008: the function definition that point is in, but the way of doing so is
        !          10009: different according to where the relevant Lisp environment is found.
        !          10010: @xref{Lisp Modes}.
        !          10011: 
        !          10012: @node Abbrevs, Picture, Compiling/Testing, Top
        !          10013: @chapter Abbrevs
        !          10014: @cindex abbrevs
        !          10015: @cindex expansion (of abbrevs)
        !          10016: 
        !          10017:   An @dfn{abbrev} is a word which @dfn{expands}, if you insert it, into some
        !          10018: different text.  Abbrevs are defined by the user to expand in specific
        !          10019: ways.  For example, you might define @samp{foo} as an abbrev expanding to
        !          10020: @samp{find outer otter}.  With this abbrev defined, you would be able to
        !          10021: get @samp{find outer otter } into the buffer by typing @kbd{f o o @key{SPC}}.
        !          10022: 
        !          10023: @cindex Abbrev mode
        !          10024: @findex abbrev-mode
        !          10025: @vindex abbrev-mode
        !          10026:   Abbrevs expand only when Abbrev mode (a minor mode) is enabled.
        !          10027: Disabling Abbrev mode does not cause abbrev definitions to be forgotten,
        !          10028: but they do not expand until Abbrev mode is enabled again.  The command
        !          10029: @kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it
        !          10030: turns Abbrev mode on if the argument is positive, off otherwise.
        !          10031: @xref{Minor Modes}.  @code{abbrev-mode} is also a variable; Abbrev mode is
        !          10032: on when the variable is non-@code{nil}.  The variable @code{abbrev-mode}
        !          10033: automatically becomes local to the current buffer when it is set.
        !          10034: 
        !          10035:   Abbrev definitions can be @dfn{mode-specific}---active only in one major
        !          10036: mode.  Abbrevs can also have @dfn{global} definitions that are active in
        !          10037: all major modes.  The same abbrev can have a global definition and various
        !          10038: mode-specific definitions for different major modes.  A mode specific
        !          10039: definition for the current major mode overrides a global definition.
        !          10040: 
        !          10041:   Abbrevs can be defined interactively during the editing session.  Lists
        !          10042: of abbrev definitions can also be saved in files and reloaded in later
        !          10043: sessions.  Some users keep extensive lists of abbrevs that they load in
        !          10044: every session.
        !          10045: 
        !          10046:   A second kind of abbreviation facility is called the @dfn{dynamic
        !          10047: expansion}.  Dynamic abbrev expansion happens only when you give an
        !          10048: explicit command and the result of the expansion depends only on the
        !          10049: current contents of the buffer.  @xref{Dynamic Abbrevs}.
        !          10050: 
        !          10051: @menu
        !          10052: * Defining Abbrevs::  Defining an abbrev, so it will expand when typed.
        !          10053: * Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion.
        !          10054: * Editing Abbrevs::   Viewing or editing the entire list of defined abbrevs.
        !          10055: * Saving Abbrevs::    Saving the entire list of abbrevs for another session.
        !          10056: * Dynamic Abbrevs::   Abbreviations for words already in the buffer.
        !          10057: @end menu
        !          10058: 
        !          10059: @node Defining Abbrevs, Expanding Abbrevs, Abbrevs, Abbrevs
        !          10060: @section Defining Abbrevs
        !          10061: 
        !          10062: @table @kbd
        !          10063: @item C-x +
        !          10064: Define an abbrev to expand into some text before point
        !          10065: (@code{add-global-abbrev}).
        !          10066: @item C-x C-a
        !          10067: Similar, but define an abbrev available only in the current major mode
        !          10068: (@code{add-mode-abbrev}).
        !          10069: @item C-x -
        !          10070: Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}).
        !          10071: @item C-x C-h
        !          10072: Define a word in the buffer as a mode-specific abbrev
        !          10073: (@code{inverse-add-mode-abbrev}).
        !          10074: @item M-x kill-all-abbrevs
        !          10075: After this command, there are no abbrev definitions in effect.
        !          10076: @end table
        !          10077: 
        !          10078: @kindex C-x +
        !          10079: @findex add-global-abbrev
        !          10080:   The usual way to define an abbrev is to enter the text you want the
        !          10081: abbrev to expand to, position point after it, and type @kbd{C-x +}
        !          10082: (@code{add-global-abbrev}).  This reads the abbrev itself using the
        !          10083: minibuffer, and then defines it as an abbrev for one or more words before
        !          10084: point.  Use a numeric argument to say how many words before point should be
        !          10085: taken as the expansion.  For example, to define the abbrev @samp{foo} as
        !          10086: mentioned above, insert the text @samp{find outer otter} and then type
        !          10087: @kbd{C-u 3 C-x + f o o @key{RET}}.
        !          10088: 
        !          10089:   An argument of zero to @kbd{C-x +} means to use the contents of the
        !          10090: region as the expansion of the abbrev being defined.
        !          10091: 
        !          10092: @kindex C-x C-a
        !          10093: @findex add-mode-abbrev
        !          10094:   The command @kbd{C-x C-a} (@code{add-mode-abbrev}) is similar, but
        !          10095: defines a mode-specific abbrev.  Mode specific abbrevs are active only in a
        !          10096: particular major mode.  @kbd{C-x C-a} defines an abbrev for the major mode
        !          10097: in effect at the time @kbd{C-x C-a} is typed.  The arguments work the same
        !          10098: as for @kbd{C-x +}.
        !          10099: 
        !          10100: @kindex C-x -
        !          10101: @findex inverse-add-global-abbrev
        !          10102: @kindex C-x C-h
        !          10103: @findex inverse-add-mode-abbrev
        !          10104:   If the text of the abbrev you want is already in the buffer instead of
        !          10105: the expansion, use command @kbd{C-x -} (@code{inverse-add-global-abbrev})
        !          10106: instead of @kbd{C-x +}, or use @kbd{C-x C-h}
        !          10107: (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x C-a}.  These commands
        !          10108: are called ``inverse'' because they invert the meaning of the argument
        !          10109: found in the buffer and the argument read using the minibuffer.@refill
        !          10110: 
        !          10111:   To change the definition of an abbrev, just add the new definition.  You
        !          10112: will be asked to confirm if the abbrev has a prior definition.  To remove
        !          10113: an abbrev definition, give a negative argument to @kbd{C-x +} or @kbd{C-x
        !          10114: C-a}.  You must choose the command to specify whether to kill a global
        !          10115: definition or a mode-specific definition for the current mode, since those
        !          10116: two definitions are independent for one abbrev.
        !          10117: 
        !          10118: @findex kill-all-abbrevs
        !          10119:   @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there are.
        !          10120: 
        !          10121: @node Expanding Abbrevs, Editing Abbrevs, Defining Abbrevs, Abbrevs
        !          10122: @section Controlling Abbrev Expansion
        !          10123: 
        !          10124:   An abbrev expands whenever it is present in the buffer just before point
        !          10125: and a self-inserting punctuation character (@key{SPC}, comma, etc.@:) is
        !          10126: typed.  Most often the way an abbrev is used is to insert the abbrev
        !          10127: followed by punctuation.
        !          10128: 
        !          10129: @vindex abbrev-all-caps
        !          10130:   Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find
        !          10131: outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into
        !          10132: @samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the
        !          10133: variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first
        !          10134: of the two expansions).@refill
        !          10135: 
        !          10136:   These two commands are used to control abbrev expansion:
        !          10137: 
        !          10138: @table @kbd
        !          10139: @item M-'
        !          10140: Separate a prefix from a following abbrev to be expanded
        !          10141: (@code{abbrev-prefix-mark}).
        !          10142: @item C-x '
        !          10143: @findex expand-abbrev
        !          10144: Expand the abbrev before point (@code{expand-abbrev}).
        !          10145: This is effective even when Abbrev mode is not enabled.
        !          10146: @item M-x unexpand-abbrev
        !          10147: Undo last abbrev expansion.
        !          10148: @item M-x expand-region-abbrevs
        !          10149: Expand some or all abbrevs found in the region.
        !          10150: @end table
        !          10151: 
        !          10152: @kindex M-'
        !          10153: @findex abbrev-prefix-mark
        !          10154:   You may wish to expand an abbrev with a prefix attached; for example, if
        !          10155: @samp{cnst} expands into @samp{construction}, you might want to use it to
        !          10156: enter @samp{reconstruction}.  It does not work to type @kbd{recnst},
        !          10157: because that is not necessarily a defined abbrev.  What does work is to use
        !          10158: the command @kbd{M-'} (@code{abbrev-prefix-mark}) in between the prefix
        !          10159: @samp{re} and the abbrev @samp{cnst}.  First, insert @samp{re}.  Then type
        !          10160: @kbd{M-'}; this inserts a minus sign in the buffer to indicate that it has
        !          10161: done its work.  Then insert the abbrev @samp{cnst}; the buffer now contains
        !          10162: @samp{re-cnst}.  Now insert a punctuation character to expand the abbrev
        !          10163: @samp{cnst} into @samp{construction}.  The minus sign is deleted at this
        !          10164: point, because @kbd{M-'} left word for this to be done.  The resulting text
        !          10165: is the desired @samp{reconstruction}.@refill
        !          10166: 
        !          10167:   If you actually want the text of the abbrev in the buffer, rather than
        !          10168: its expansion, you can accomplish this by inserting the following
        !          10169: punctuation with @kbd{C-q}.  Thus, @kbd{foo C-q -} leaves @samp{foo-} in the
        !          10170: buffer.
        !          10171: 
        !          10172: @findex unexpand-abbrev
        !          10173:   If you expand an abbrev by mistake, you can undo the expansion (replace
        !          10174: the expansion by the original abbrev text) with @kbd{M-x unexpand-abbrev}.
        !          10175: @kbd{C-_} (@code{undo}) can also be used to undo the expansion; but first
        !          10176: it will undo the insertion of the following punctuation character!
        !          10177: 
        !          10178: @findex expand-region-abbrevs
        !          10179:   @kbd{M-x expand-region-abbrevs} searches through the region for defined
        !          10180: abbrevs, and for each one found offers to replace it with its expansion.
        !          10181: This command is useful if you have typed in text using abbrevs but forgot
        !          10182: to turn on Abbrev mode first.  It may also be useful together with a
        !          10183: special set of abbrev definitions for making several global replacements at
        !          10184: once.  This command is effective even if Abbrev mode is not enabled.
        !          10185: 
        !          10186: @node Editing Abbrevs, Saving Abbrevs, Expanding Abbrevs, Abbrevs
        !          10187: @section Examining and Editing Abbrevs
        !          10188: 
        !          10189: @table @kbd
        !          10190: @item M-x list-abbrevs
        !          10191: Print a list of all abbrev definitions.
        !          10192: @item M-x edit-abbrevs
        !          10193: Edit a list of abbrevs; you can add, alter or remove definitions.
        !          10194: @end table
        !          10195: 
        !          10196: @findex list-abbrevs
        !          10197:   The output from @kbd{M-x list-abbrevs} looks like this:
        !          10198: 
        !          10199: @example
        !          10200: (lisp-mode-abbrev-table)
        !          10201: "dk"          0    "define-key"
        !          10202: (global-abbrev-table)
        !          10203: "dfn"         0    "definition"
        !          10204: @end example
        !          10205: 
        !          10206: @noindent
        !          10207: (Some blank lines of no semantic significance, and some other abbrev
        !          10208: tables, have been omitted.)
        !          10209: 
        !          10210:   A line containing a name in parentheses is the header for abbrevs in a
        !          10211: particular abbrev table; @code{global-abbrev-table} contains all the global
        !          10212: abbrevs, and the other abbrev tables that are named after major modes
        !          10213: contain the mode-specific abbrevs.
        !          10214: 
        !          10215:   Within each abbrev table, each nonblank line defines one abbrev.  The
        !          10216: word at the beginning is the abbrev.  The number that appears is the number
        !          10217: of times the abbrev has been expanded.  Emacs keeps track of this to help
        !          10218: you see which abbrevs you actually use, in case you decide to eliminate
        !          10219: those that you don't use often.  The string at the end of the line is the
        !          10220: expansion.
        !          10221: 
        !          10222: @findex edit-abbrevs
        !          10223: @kindex C-c C-c (Edit Abbrevs)
        !          10224: @findex edit-abbrevs-redefine
        !          10225: @cindex Edit-Abbrevs mode
        !          10226:   @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev
        !          10227: definitions by editing a list of them in an Emacs buffer.  The list has the
        !          10228: same format described above.  The buffer of abbrevs is called @samp{*Abbrevs*},
        !          10229: and is in Edit-Abbrevs mode.  This mode redefines the key @kbd{C-c C-c} to
        !          10230: install the abbrev definitions as specified in the buffer.  The command
        !          10231: that does this is @code{edit-abbrevs-redefine}.  Any abbrevs not described
        !          10232: in the buffer are eliminated when this is done.
        !          10233: 
        !          10234:   @code{edit-abbrevs} is actually the same as @code{list-abbrevs} except
        !          10235: that it selects the buffer @samp{*Abbrevs*} whereas @code{list-abbrevs}
        !          10236: merely displays it in another window.
        !          10237: 
        !          10238: @node Saving Abbrevs, Dynamic Abbrevs, Editing Abbrevs, Abbrevs
        !          10239: @section Saving Abbrevs
        !          10240: 
        !          10241:   These commands allow you to keep abbrev definitions between editing
        !          10242: sessions.
        !          10243: 
        !          10244: @table @kbd
        !          10245: @item M-x write-abbrev-file
        !          10246: Write a file describing all defined abbrevs.
        !          10247: @item M-x read-abbrev-file
        !          10248: Read such a file and define abbrevs as specified there.
        !          10249: @item M-x quietly-read-abbrev-file
        !          10250: Similar but do not display a message about what is going on.
        !          10251: @item M-x define-abbrevs
        !          10252: Define abbrevs from buffer.
        !          10253: @item M-x insert-abbrevs
        !          10254: Insert all abbrevs and their expansions into the buffer.
        !          10255: @end table
        !          10256: 
        !          10257: @findex write-abbrev-file
        !          10258:   @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and
        !          10259: writes a description of all current abbrev definitions into that file.  The
        !          10260: text stored in the file looks like the output of @kbd{M-x list-abbrevs}.
        !          10261: This is used to save abbrev definitions for use in a later session.
        !          10262: 
        !          10263: @findex read-abbrev-file
        !          10264: @findex quietly-read-abbrev-file
        !          10265: @vindex abbrev-file-name
        !          10266:   @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and
        !          10267: reads the file, defining abbrevs according to the contents of the file.
        !          10268: @kbd{M-x quietly-read-abbrev-file} is the same except that it does not
        !          10269: display a message in the echo area saying that it is doing its work; it
        !          10270: is actually useful primarily in the @file{.emacs} file.  If an empty
        !          10271: argument is given to either of these functions, the file name used is the
        !          10272: value of the variable @code{abbrev-file-name}, which is by default
        !          10273: @code{"~/.abbrev_defs"}.
        !          10274: 
        !          10275: @vindex save-abbrevs
        !          10276:   Emacs will offer to save abbrevs automatically if you have changed any of
        !          10277: them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x
        !          10278: C-c}).  This feature can be inhibited by setting the variable
        !          10279: @code{save-abbrevs} to @code{nil}.
        !          10280: 
        !          10281: @findex insert-abbrevs
        !          10282: @findex define-abbrevs
        !          10283:   The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are
        !          10284: similar to the previous commands but work on text in an Emacs buffer.
        !          10285: @kbd{M-x insert-abbrevs} inserts text into the current buffer before point,
        !          10286: describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses
        !          10287: the entire current buffer and defines abbrevs accordingly.@refill
        !          10288: 
        !          10289: @node Dynamic Abbrevs,, Saving Abbrevs, Abbrevs
        !          10290: @section Dynamic Abbrev Expansion
        !          10291: @cindex dynamic abbrevs
        !          10292: 
        !          10293:   The abbrev facility described above operates automatically as you insert
        !          10294: text, but all abbrevs must be defined explicitly.  By contrast,
        !          10295: @dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined
        !          10296: automatically from the contents of the buffer, but dynamic abbrev expansion
        !          10297: happens only when you request it explicitly.
        !          10298: 
        !          10299: @kindex M-/
        !          10300: @findex dabbrev-expand
        !          10301: @table @kbd
        !          10302: @item M-/
        !          10303: Expand the word in the buffer before point as a @dfn{dynamic abbrev},
        !          10304: by searching in the buffer for words starting with that abbreviation
        !          10305: (@code{dabbrev-expand}).
        !          10306: @end table
        !          10307: 
        !          10308:   For example, if the buffer contains @samp{does this follow } and you type
        !          10309: @w{@kbd{f o M-/}}, the effect is to insert @samp{follow} because that is
        !          10310: the last word in the buffer that starts with @samp{fo}.  A numeric
        !          10311: argument to @kbd{M-/} says to take the second, third, etc.@: distinct
        !          10312: expansion found looking backward from point.  Repeating @kbd{M-/}
        !          10313: searches for an alternative expansion by looking farther back.  After
        !          10314: the part of the buffer preceding point has been considered, the part
        !          10315: of the buffer after point is searched.
        !          10316: 
        !          10317:   Dynamic abbrev expansion is completely independent of Abbrev mode; the
        !          10318: expansion of a word with @kbd{M-/} is completely independent of whether it
        !          10319: has a definition as an ordinary abbrev.
        !          10320: 
        !          10321: @node Picture, Sending Mail, Abbrevs, Top
        !          10322: @chapter Editing Pictures
        !          10323: @cindex pictures
        !          10324: @findex edit-picture
        !          10325: @cindex Picture mode
        !          10326: 
        !          10327:   If you want to create a picture made out of text characters (for example,
        !          10328: a picture of the division of a register into fields, as a comment in a
        !          10329: program), use the command @code{edit-picture} to enter Picture mode.
        !          10330: 
        !          10331:   In Picture mode, editing is based on the @dfn{quarter-plane} model of
        !          10332: text, according to which the text characters lie studded on an area that
        !          10333: stretches infinitely far to the right and downward.  The concept of the end
        !          10334: of a line does not exist in this model; the most you can say is where the
        !          10335: last nonblank character on the line is found.
        !          10336: 
        !          10337:   Of course, Emacs really always considers text as a sequence of
        !          10338: characters, and lines really do have ends.  But in Picture mode most
        !          10339: frequently-used keys are rebound to commands that simulate the
        !          10340: quarter-plane model of text.  They do this by inserting spaces or by
        !          10341: converting tabs to spaces.
        !          10342: 
        !          10343:   Most of the basic editing commands of Emacs are redefined by Picture mode
        !          10344: to do essentially the same thing but in a quarter-plane way.  In addition,
        !          10345: Picture mode defines various keys starting with the @kbd{C-c} prefix to
        !          10346: run special picture editing commands.
        !          10347: 
        !          10348:   One of these keys, @kbd{C-c C-c}, is pretty important.  Often a picture
        !          10349: is part of a larger file that is usually edited in some other major mode.
        !          10350: @kbd{M-x edit-picture} records the name of the previous major mode, and
        !          10351: then you can use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to
        !          10352: restore that mode.  @kbd{C-c C-c} also deletes spaces from the ends of
        !          10353: lines, unless given a numeric argument.
        !          10354: 
        !          10355:   The commands used in Picture mode all work in other modes (provided the
        !          10356: @file{picture} library is loaded), but are not bound to keys except in
        !          10357: Picture mode.  Note that the descriptions below talk of moving ``one
        !          10358: column'' and so on, but all the picture mode commands handle numeric
        !          10359: arguments as their normal equivalents do.
        !          10360: 
        !          10361: @vindex picture-mode-hook
        !          10362:   Turning on Picture mode calls the value of the variable @code{picture-mode-hook}
        !          10363: as a function, with no arguments, if that value exists and is non-@code{nil}.
        !          10364: 
        !          10365: @menu
        !          10366: * Basic Picture::         Basic concepts and simple commands of Picture Mode.
        !          10367: * Insert in Picture::     Controlling direction of cursor motion
        !          10368:                            after "self-inserting" characters.
        !          10369: * Tabs in Picture::       Various features for tab stops and indentation.
        !          10370: * Rectangles in Picture:: Clearing and superimposing rectangles.
        !          10371: @end menu
        !          10372: 
        !          10373: @node Basic Picture, Insert in Picture, Picture, Picture
        !          10374: @section Basic Editing in Picture Mode
        !          10375: 
        !          10376: @findex picture-forward-column
        !          10377: @findex picture-backward-column
        !          10378: @findex picture-move-down
        !          10379: @findex picture-move-up
        !          10380:   Most keys do the same thing in Picture mode that they usually do, but do
        !          10381: it in a quarter-plane style.  For example, @kbd{C-f} is rebound to run
        !          10382: @code{picture-forward-column}, which is defined to move point one column to
        !          10383: the right, by inserting a space if necessary, so that the actual end of the
        !          10384: line makes no difference.  @kbd{C-b} is rebound to run
        !          10385: @code{picture-backward-column}, which always moves point left one column,
        !          10386: converting a tab to multiple spaces if necessary.  @kbd{C-n} and @kbd{C-p}
        !          10387: are rebound to run @code{picture-move-down} and @code{picture-move-up},
        !          10388: which can either insert spaces or convert tabs as necessary to make sure
        !          10389: that point stays in exactly the same column.  @kbd{C-e} runs
        !          10390: @code{picture-end-of-line}, which moves to after the last nonblank
        !          10391: character on the line.  There is no need to change @kbd{C-a}, as the choice
        !          10392: of screen model does not affect beginnings of lines.@refill
        !          10393: 
        !          10394: @findex picture-newline
        !          10395:   Insertion of text is adapted to the quarter-plane screen model through
        !          10396: the use of Overwrite mode (@pxref{Minor Modes}).  Self-inserting characters
        !          10397: replace existing text, column by column, rather than pushing existing text
        !          10398: to the right.  @key{RET} runs @code{picture-newline}, which just moves to
        !          10399: the beginning of the following line so that new text will replace that
        !          10400: line.
        !          10401: 
        !          10402: @findex picture-backward-clear-column
        !          10403: @findex picture-clear-column
        !          10404: @findex picture-clear-line
        !          10405:   Deletion and killing of text are replaced with erasure.  @key{DEL}
        !          10406: (@code{picture-backward-clear-column}) replaces the preceding character
        !          10407: with a space rather than removing it.  @kbd{C-d}
        !          10408: (@code{picture-clear-column}) does the same thing in a forward direction.
        !          10409: @kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines,
        !          10410: but does not ever remove the newlines from the buffer.@refill
        !          10411: 
        !          10412: @findex picture-open-line
        !          10413:   To do actual insertion, you must use special commands.  @kbd{C-o}
        !          10414: (@code{picture-open-line}) still creates a blank line, but does so after
        !          10415: the current line; it never splits a line.  @kbd{C-M-o}, @code{split-line},
        !          10416: makes sense in Picture mode, so it is not changed.  @key{LFD}
        !          10417: (@code{picture-duplicate-line}) inserts below the current line another line
        !          10418: with the same contents.@refill
        !          10419: 
        !          10420: @kindex C-c C-d (Picture mode)
        !          10421: @findex delete-char
        !          10422:   Real deletion can be done with @kbd{C-w}, or with @kbd{C-c C-d} (which is
        !          10423: defined as @code{delete-char}, as @kbd{C-d} is in other modes), or with one
        !          10424: of the picture rectangle commands (@pxref{Rectangles in Picture}).
        !          10425: 
        !          10426: @node Insert in Picture, Tabs in Picture, Basic Picture, Picture
        !          10427: @section Controlling Motion after Insert
        !          10428: 
        !          10429: @findex picture-movement-up
        !          10430: @findex picture-movement-down
        !          10431: @findex picture-movement-left
        !          10432: @findex picture-movement-right
        !          10433: @findex picture-movement-nw
        !          10434: @findex picture-movement-ne
        !          10435: @findex picture-movement-sw
        !          10436: @findex picture-movement-se
        !          10437: @kindex C-c < (Picture mode)
        !          10438: @kindex C-c > (Picture mode)
        !          10439: @kindex C-c ^ (Picture mode)
        !          10440: @kindex C-c . (Picture mode)
        !          10441: @kindex C-c ` (Picture mode)
        !          10442: @kindex C-c ' (Picture mode)
        !          10443: @kindex C-c / (Picture mode)
        !          10444: @kindex C-c \ (Picture mode)
        !          10445:   Since ``self-inserting'' characters in Picture mode just overwrite and
        !          10446: move point, there is no essential restriction on how point should be moved.
        !          10447: Normally point moves right, but you can specify any of the eight orthogonal
        !          10448: or diagonal directions for motion after a ``self-inserting'' character.
        !          10449: This is useful for drawing lines in the buffer.
        !          10450: 
        !          10451: @table @kbd
        !          10452: @item C-c <
        !          10453: Move left after insertion (@code{picture-movement-left}).
        !          10454: @item C-c >
        !          10455: Move right after insertion (@code{picture-movement-right}).
        !          10456: @item C-c ^
        !          10457: Move up after insertion (@code{picture-movement-up}).
        !          10458: @item C-c .
        !          10459: Move down after insertion (@code{picture-movement-down}).
        !          10460: @c !!! added @* to prevent overfull hbox
        !          10461: @item C-c `
        !          10462: Move up and left (``northwest'') after insertion@*
        !          10463: (@code{picture-movement-nw}).
        !          10464: @item C-c '
        !          10465: Move up and right (``northeast'') after insertion
        !          10466: (@code{picture-movement-ne}).
        !          10467: @item C-c /
        !          10468: Move down and left (``southwest'') after insertion
        !          10469: (@code{picture-movement-sw}).
        !          10470: @item C-c \
        !          10471: Move down and right (``southeast'') after insertion
        !          10472: (@code{picture-movement-se}).
        !          10473: @end table
        !          10474: 
        !          10475: @kindex C-c C-f (Picture mode)
        !          10476: @kindex C-c C-b (Picture mode)
        !          10477: @findex picture-motion
        !          10478: @findex picture-motion-reverse
        !          10479:   Two motion commands move based on the current Picture insertion
        !          10480: direction.  The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
        !          10481: same direction as motion after ``insertion'' currently does, while @kbd{C-c
        !          10482: C-b} (@code{picture-motion-reverse}) moves in the opposite direction.
        !          10483: 
        !          10484: @node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
        !          10485: @section Picture Mode Tabs
        !          10486: 
        !          10487: @kindex M-TAB
        !          10488: @findex picture-tab-search
        !          10489: @vindex picture-tab-chars
        !          10490:   Two kinds of tab-like action are provided in Picture mode.
        !          10491: Context-based tabbing is done with @kbd{M-@key{TAB}}
        !          10492: (@code{picture-tab-search}).  With no argument, it moves to a point
        !          10493: underneath the next ``interesting'' character that follows whitespace in
        !          10494: the previous nonblank line.  ``Next'' here means ``appearing at a
        !          10495: horizontal position greater than the one point starts out at''.  With an
        !          10496: argument, as in @kbd{C-u M-@key{TAB}}, this command moves to the next such
        !          10497: interesting character in the current line.  @kbd{M-@key{TAB}} does not
        !          10498: change the text; it only moves point.  ``Interesting'' characters are
        !          10499: defined by the variable @code{picture-tab-chars}, which contains a string
        !          10500: whose characters are all considered interesting.  Its default value is
        !          10501: @code{"!-~"}.@refill
        !          10502: 
        !          10503: @findex picture-tab
        !          10504:   @key{TAB} itself runs @code{picture-tab}, which operates based on the
        !          10505: current tab stop settings; it is the Picture mode equivalent of
        !          10506: @code{tab-to-tab-stop}.  Normally it just moves point, but with a numeric
        !          10507: argument it clears the text that it moves over.
        !          10508: 
        !          10509: @kindex C-c TAB (Picture mode)
        !          10510: @findex picture-set-tab-stops
        !          10511:   The context-based and tab-stop-based forms of tabbing are brought
        !          10512: together by the command @kbd{C-c @key{TAB}}, @code{picture-set-tab-stops}.
        !          10513: This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
        !          10514: would consider significant in the current line.  The use of this command,
        !          10515: together with @key{TAB}, can get the effect of context-based tabbing.  But
        !          10516: @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.
        !          10517: 
        !          10518: @node Rectangles in Picture,, Tabs in Picture, Picture
        !          10519: @section Picture Mode Rectangle Commands
        !          10520: @cindex rectangles and Picture mode
        !          10521: 
        !          10522:   Picture mode defines commands for working on rectangular pieces of the
        !          10523: text in ways that fit with the quarter-plane model.  The standard rectangle
        !          10524: commands may also be useful (@pxref{Rectangles}).
        !          10525: 
        !          10526: @table @kbd
        !          10527: @item C-c C-k
        !          10528: Clear out the region-rectangle (@code{picture-clear-rectangle}).  With
        !          10529: argument, kill it.
        !          10530: @item C-c C-w @var{r}
        !          10531: Similar but save rectangle contents in register @var{r} first
        !          10532: (@code{picture-clear-rectangle-to-register}).
        !          10533: @item C-c C-y
        !          10534: Copy last killed rectangle into the buffer by overwriting, with upper
        !          10535: left corner at point (@code{picture-yank-rectangle}).  With argument,
        !          10536: insert instead.
        !          10537: @item C-c C-x @var{r}
        !          10538: Similar, but use the rectangle in register @var{r}
        !          10539: (@code{picture-yank-rectangle-from-register}).
        !          10540: @end table
        !          10541: 
        !          10542: @kindex C-c C-k (Picture mode)
        !          10543: @kindex C-c C-w (Picture mode)
        !          10544: @findex picture-clear-rectangle
        !          10545: @findex picture-clear-rectangle-to-register
        !          10546:   The picture rectangle commands @kbd{C-c C-k}
        !          10547: (@code{picture-clear-rectangle}) and @kbd{C-c C-w}
        !          10548: (@code{picture-clear-rectangle-to-register}) differ from the standard
        !          10549: rectangle commands in that they normally clear the rectangle instead of
        !          10550: deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
        !          10551: mode.@refill
        !          10552: 
        !          10553:   However, deletion of rectangles can be useful in Picture mode, so these
        !          10554: commands delete the rectangle if given a numeric argument.
        !          10555: 
        !          10556: @kindex C-c C-y (Picture mode)
        !          10557: @kindex C-c C-x (Picture mode)
        !          10558: @findex picture-yank-rectangle
        !          10559: @findex picture-yank-rectangle-from-register
        !          10560:   The Picture mode commands for yanking rectangles differ from the standard
        !          10561: ones in overwriting instead of inserting.  This is the same way that
        !          10562: Picture mode insertion of other text is different from other modes.
        !          10563: @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) the
        !          10564: rectangle that was most recently killed, while @kbd{C-c C-x}
        !          10565: (@code{picture-yank-rectangle-from-register}) does likewise for the
        !          10566: rectangle found in a specified register.
        !          10567: 
        !          10568: @node Sending Mail, Rmail, Picture, Top
        !          10569: @chapter Sending Mail
        !          10570: @cindex mail
        !          10571: @cindex message
        !          10572: 
        !          10573:   To send a message in Emacs, you start by typing a command (@kbd{C-x m})
        !          10574: to select and initialize the @samp{*mail*} buffer.  Then you edit the text
        !          10575: and headers of the message in this buffer, and type another command
        !          10576: (@kbd{C-c C-c}) to send the message.
        !          10577: 
        !          10578: @table @kbd
        !          10579: @item C-x m
        !          10580: Begin composing a message to send (@code{mail}).
        !          10581: @item C-x 4 m
        !          10582: Likewise, but display the message in another window
        !          10583: (@code{mail-other-window}).
        !          10584: @item C-c C-c
        !          10585: In Mail mode, send the message and switch to another buffer
        !          10586: (@code{mail-send-and-exit}).
        !          10587: @end table
        !          10588: 
        !          10589: @kindex C-x m
        !          10590: @findex mail
        !          10591: @kindex C-x 4 m
        !          10592: @findex mail-other-window
        !          10593:   The command @kbd{C-x m} (@code{mail}) selects a buffer named
        !          10594: @samp{*mail*} and initializes it with the skeleton of an outgoing message.
        !          10595: @kbd{C-x 4 m} (@code{mail-other-window}) selects the @samp{*mail*} buffer
        !          10596: in a different window, leaving the previous current buffer visible.@refill
        !          10597: 
        !          10598:   Because the mail composition buffer is an ordinary Emacs buffer, you can
        !          10599: switch to other buffers while in the middle of composing mail, and switch
        !          10600: back later (or never).  If you use the @kbd{C-x m} command again when you
        !          10601: have been composing another message but have not sent it, you are asked to
        !          10602: confirm before the old message is erased.  If you answer @kbd{n}, the
        !          10603: @samp{*mail*} buffer is left selected with its old contents, so you can
        !          10604: finish the old message and send it.  @kbd{C-u C-x m} is another way to do
        !          10605: this.  Sending the message marks the @samp{*mail*} buffer ``unmodified'',
        !          10606: which avoids the need for confirmation when @kbd{C-x m} is next used.
        !          10607: 
        !          10608:   If you are composing a message in the @samp{*mail*} buffer and want to
        !          10609: send another message before finishing the first, rename the @samp{*mail*}
        !          10610: buffer using @kbd{M-x rename-buffer} (@pxref{Misc Buffer}).
        !          10611: 
        !          10612: @menu
        !          10613: * Format: Mail Format.    Format of the mail being composed.
        !          10614: * Headers: Mail Headers.  Details of allowed mail header fields.
        !          10615: * Mode: Mail Mode.        Special commands for editing mail being composed.
        !          10616: @end menu
        !          10617: 
        !          10618: @node Mail Format, Mail Headers, Sending Mail, Sending Mail
        !          10619: @section The Format of the Mail Buffer
        !          10620: 
        !          10621:   In addition to the @dfn{text} or contents, a message has @dfn{header
        !          10622: fields} which say who sent it, when, to whom, why, and so on.  Some header
        !          10623: fields such as the date and sender are created automatically after the
        !          10624: message is sent.  Others, such as the recipient names, must be specified by
        !          10625: you in order to send the message properly.
        !          10626: 
        !          10627:   Mail mode provides a few commands to help you edit some header fields,
        !          10628: and some are preinitialized in the buffer automatically at times.  You can
        !          10629: insert or edit any header fields using ordinary editing commands.
        !          10630: 
        !          10631:   The line in the buffer that says
        !          10632: 
        !          10633: @example
        !          10634: --text follows this line--
        !          10635: @end example
        !          10636: 
        !          10637: @vindex mail-header-separator
        !          10638: @noindent
        !          10639: is a special delimiter that separates the headers you have specified from
        !          10640: the text.  Whatever follows this line is the text of the message; the
        !          10641: headers precede it.  The delimiter line itself does not appear in the
        !          10642: message actually sent.  The text used for the delimiter line is controlled
        !          10643: by the variable @code{mail-header-separator}.
        !          10644: 
        !          10645: Here is an example of what the headers and text in the @samp{*mail*} buffer
        !          10646: might look like.
        !          10647: 
        !          10648: @example
        !          10649: To: rms@@mc
        !          10650: CC: mly@@mc, rg@@oz
        !          10651: Subject: The Emacs Manual
        !          10652: --Text follows this line--
        !          10653: Please ignore this message.
        !          10654: @end example
        !          10655: 
        !          10656: @node Mail Headers, Mail Mode, Mail Format, Sending Mail
        !          10657: @section Mail Header Fields
        !          10658: @cindex headers (of mail message)
        !          10659: 
        !          10660:   There are several header fields you can use in the @samp{*mail*} buffer.
        !          10661: Each header field starts with a field name at the beginning of a line,
        !          10662: terminated by a colon.  It does not matter whether you use upper or lower
        !          10663: case in the field name.  After the colon and optional whitespace comes the
        !          10664: contents of the field.
        !          10665: 
        !          10666: @table @samp
        !          10667: @item To
        !          10668: This field contains the mailing addresses to which the message is
        !          10669: addressed.
        !          10670: 
        !          10671: @item Subject
        !          10672: The contents of the @samp{Subject} field should be a piece of text
        !          10673: that says what the message is about.  The reason @samp{Subject} fields
        !          10674: are useful is that most mail-reading programs can provide a summary of
        !          10675: messages, listing the subject of each message but not its text.
        !          10676: 
        !          10677: @item CC
        !          10678: This field contains additional mailing addresses to send the message
        !          10679: to, but whose readers should not regard the message as addressed to
        !          10680: them.
        !          10681: 
        !          10682: @item BCC
        !          10683: This field contains additional mailing addresses to send the message
        !          10684: to, but which should not appear in the header of the message actually
        !          10685: sent.
        !          10686: 
        !          10687: @item FCC
        !          10688: This field contains the name of one file (in Unix mail file format) to
        !          10689: which a copy of the message should be appended when the message is
        !          10690: sent.
        !          10691: 
        !          10692: @item From
        !          10693: Use the @samp{From} field to say who you are, when the account you are
        !          10694: using to send the mail is not your own.  The contents of the
        !          10695: @samp{From} field should be a valid mailing address, since replies
        !          10696: will normally go there.
        !          10697: 
        !          10698: @item Reply-To
        !          10699: Use the @samp{Reply-to} field to direct replies to a different
        !          10700: address, not your own.  There is no difference between @samp{From} and
        !          10701: @samp{Reply-to} in their effect on where replies go, but they convey a
        !          10702: different meaning to the human who reads the message.
        !          10703: 
        !          10704: @vindex mail-default-reply-to
        !          10705: If you set the variable @code{mail-default-reply-to} to a non-@code{nil}
        !          10706: value, then every message you begin to edit will have a @samp{Reply-to}
        !          10707: field whose contents are the value of the variable.
        !          10708: 
        !          10709: @item In-Reply-To
        !          10710: This field contains a piece of text describing a message you are
        !          10711: replying to.  Some mail systems can use this information to correlate
        !          10712: related pieces of mail.  Normally this field is filled in by Rmail
        !          10713: when you are replying to a message in Rmail, and you never need to
        !          10714: think about it (@pxref{Rmail}).
        !          10715: @end table
        !          10716: 
        !          10717: The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} fields can appear
        !          10718: any number of times, to specify many places to send the message.
        !          10719: 
        !          10720: The @samp{To}, @samp{CC}, and @samp{BCC} fields can have continuation
        !          10721: lines.  All the lines starting with whitespace, following the line on
        !          10722: which the field starts, are considered part of the field.  For
        !          10723: example,@refill
        !          10724: 
        !          10725: @example
        !          10726: @group
        !          10727: To: foo@@here, this@@there,
        !          10728:   me@@gnu.cambridge.mass.usa.earth.spiral3281
        !          10729: @end group
        !          10730: @end example
        !          10731: 
        !          10732: If you have a @file{~/.mailrc} file, Emacs will scan it for mail aliases
        !          10733: the first time you try to send mail in an Emacs session.  Aliases found
        !          10734: in the @samp{To}, @samp{CC}, and @samp{BCC} fields will be expanded where
        !          10735: appropriate.
        !          10736: 
        !          10737: @vindex mail-archive-file-name
        !          10738:   If the variable @code{mail-archive-file-name} is non-@code{nil}, it should be a
        !          10739: string naming a file; every time you start to edit a message to send,
        !          10740: an @samp{FCC} field will be put in for that file.  Unless you remove the
        !          10741: @samp{FCC} field, every message will be written into that file when it is
        !          10742: sent.
        !          10743: 
        !          10744: @node Mail Mode,, Mail Headers, Sending Mail
        !          10745: @section Mail Mode
        !          10746: @cindex Mail mode
        !          10747: 
        !          10748:   The major mode used in the @samp{*mail*} buffer is Mail mode, which is
        !          10749: much like Text mode except that various special commands are provided on
        !          10750: the @w{@kbd{C-c}} prefix.  These commands all have to do specifically with
        !          10751: editing or sending the message.
        !          10752: 
        !          10753: @table @kbd
        !          10754: @item C-c C-s
        !          10755: Send the message, and leave the @samp{*mail*} buffer selected
        !          10756: (@code{mail-send}).
        !          10757: @item C-c C-c
        !          10758: Send the message, and select some other buffer (@code{mail-send-and-exit}).
        !          10759: @item C-c C-f C-t
        !          10760: Move to the @samp{To} header field, creating one if there is none
        !          10761: (@code{mail-to}).
        !          10762: @item C-c C-f C-s
        !          10763: Move to the @samp{Subject} header field, creating one if there is
        !          10764: none (@code{mail-subject}).
        !          10765: @item C-c C-f C-c
        !          10766: Move to the @samp{CC} header field, creating one if there is none
        !          10767: (@code{mail-cc}).
        !          10768: @item C-c C-w
        !          10769: Insert the file @file{~/.signature} at the end of the message text
        !          10770: (@code{mail-signature}).
        !          10771: @item C-c C-y
        !          10772: Yank the selected message from Rmail (@code{mail-yank-original}).
        !          10773: This command does nothing unless your command to start sending a
        !          10774: message was issued with Rmail.
        !          10775: @item C-c C-q
        !          10776: Fill all paragraphs of yanked old messages, each individually
        !          10777: (@code{mail-fill-yanked-message}).
        !          10778: @end table
        !          10779: 
        !          10780: @kindex C-c C-s (Mail mode)
        !          10781: @kindex C-c C-c (Mail mode)
        !          10782: @findex mail-send
        !          10783: @findex mail-send-and-exit
        !          10784:   There are two ways to send the message.  @kbd{C-c C-s} (@code{mail-send})
        !          10785: sends the message and marks the @samp{*mail*} buffer unmodified, but leaves
        !          10786: that buffer selected so that you can modify the message (perhaps with new
        !          10787: recipients) and send it again.  @kbd{C-c C-c} (@code{mail-send-and-exit})
        !          10788: sends and then deletes the window (if there is another window) or switches
        !          10789: to another buffer.  It puts the @samp{*mail*} buffer at the lowest priority
        !          10790: for automatic reselection, since you are finished with using it.  This is
        !          10791: the usual way to send the message.
        !          10792: 
        !          10793: @kindex C-c C-f C-t (Mail mode)
        !          10794: @findex mail-to
        !          10795: @kindex C-c C-f C-s (Mail mode)
        !          10796: @findex mail-subject
        !          10797: @kindex C-c C-f C-c (Mail mode)
        !          10798: @findex mail-cc
        !          10799:   Mail mode provides some other special commands that are useful for
        !          10800: editing the headers and text of the message before you send it.  There are
        !          10801: three commands defined to move point to particular header fields, all based
        !          10802: on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field'').  They are
        !          10803: @kbd{C-c C-f C-t} (@code{mail-to}) to move to the @samp{To} field, @kbd{C-c
        !          10804: C-f C-s} (@code{mail-subject}) for the @samp{Subject} field, and @kbd{C-c
        !          10805: C-f C-c} (@code{mail-cc}) for the @samp{CC} field.  These fields have
        !          10806: special motion commands because they are the most common fields for the
        !          10807: user to want to edit.
        !          10808: 
        !          10809: @kindex C-c C-w (Mail mode)
        !          10810: @findex mail-signature
        !          10811:   @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece text at the end of the
        !          10812: message to say more about who you are.  The text comes from the file
        !          10813: @file{.signature} in your home directory.
        !          10814: 
        !          10815: @kindex C-c C-y (Mail mode)
        !          10816: @findex mail-yank-original
        !          10817:   When mail sending is invoked from the Rmail mail reader using an Rmail
        !          10818: command, @kbd{C-c C-y} can be used inside the @samp{*mail*} buffer to insert
        !          10819: the text of the message you are replying to.  Normally it indents each line
        !          10820: of that message four spaces and eliminates most header fields.  A numeric
        !          10821: argument specifies the number of spaces to indent.  An argument of just
        !          10822: @kbd{C-u} says not to indent at all and not to eliminate anything.
        !          10823: @kbd{C-c C-y} always uses the current message from the @samp{RMAIL} buffer,
        !          10824: so you can insert several old messages by selecting one in @samp{RMAIL},
        !          10825: switching to @samp{*mail*} and yanking it, then switching back to
        !          10826: @samp{RMAIL} to select another.@refill
        !          10827: 
        !          10828: @kindex C-c C-q (Mail mode)
        !          10829: @findex mail-fill-yanked-message
        !          10830: @c !!! the following is verbose to prevent an overfull hbox
        !          10831:   After using @kbd{C-c C-y}, you can type
        !          10832: the command @kbd{C-c C-q} (@code{mail-fill-yanked-message}) to
        !          10833: fill the paragraphs of the yanked old message or messages.  One
        !          10834: use of @kbd{C-c C-q} fills all such paragraphs, each one separately.
        !          10835: 
        !          10836: @vindex mail-mode-hook
        !          10837: @vindex mail-setup-hook
        !          10838:   Turning on Mail mode (which @kbd{C-x m} does automatically) calls the
        !          10839: value of @code{text-mode-hook}, if it is not void or @code{nil}, and
        !          10840: then calls the value of @code{mail-mode-hook} if that is not void or
        !          10841: @code{nil}.  Aside from these, the @code{mail} command runs
        !          10842: @code{mail-setup-hook} whenever it initializes the @samp{*mail*} buffer
        !          10843: for editing a message.
        !          10844: 
        !          10845: @node Rmail, Recursive Edit, Sending Mail, Top
        !          10846: @chapter Reading Mail with Rmail
        !          10847: @cindex Rmail
        !          10848: @cindex message
        !          10849: @findex rmail
        !          10850: @cindex Rmail mode
        !          10851: 
        !          10852:   Rmail is an Emacs subsystem for reading and disposing of mail that you
        !          10853: receive.  Rmail stores mail messages in files called @dfn{Rmail
        !          10854: files}.  Reading the message in an Rmail file is done in a special
        !          10855: major mode, Rmail mode, which redefines most letters to run commands
        !          10856: for managing mail.  To enter Rmail, type @kbd{M-x rmail}.  This reads
        !          10857: your primary mail file, merges new mail in from your inboxes, displays
        !          10858: the first new message, and lets you begin reading.
        !          10859: 
        !          10860: @cindex primary mail file
        !          10861:   Using Rmail in the simplest fashion, you have one Rmail file, @file{~/RMAIL},
        !          10862: in which all of your mail is saved.  It is called your @dfn{primary mail
        !          10863: file}.  In more sophisticated usage, you can copy messages into other Rmail
        !          10864: files and then edit those files with Rmail.
        !          10865: 
        !          10866:   Rmail displays only one message at a time.  It is called the @dfn{current
        !          10867: message}.  Rmail mode's special commands can do such things as move to
        !          10868: another message, delete the message, copy the message into another file, or
        !          10869: send a reply.
        !          10870: 
        !          10871: @cindex message number
        !          10872:   Within the Rmail file, messages are arranged sequentially in order
        !          10873: of receipt.  They are also assigned consecutive integers as their
        !          10874: @dfn{message numbers}.  The number of the current message is displayed
        !          10875: in Rmail's mode line, followed by the total number of messages in the
        !          10876: file.  You can move to a message by specifying its message number
        !          10877: using the @kbd{j} key (@pxref{Rmail Motion}).
        !          10878: 
        !          10879: @kindex s (Rmail)
        !          10880: @findex rmail-save
        !          10881:   Following the usual conventions of Emacs, changes in an Rmail file become
        !          10882: permanent only when the file is saved.  You can do this with @kbd{s}
        !          10883: (@code{rmail-save}), which also expunges deleted messages from the file
        !          10884: first (@pxref{Rmail Deletion}).  To save the file without expunging, use
        !          10885: @kbd{C-x C-s}.  Rmail saves the Rmail file spontaneously when moving new
        !          10886: mail from an inbox file (@pxref{Rmail Inbox}).
        !          10887: 
        !          10888: @kindex q (Rmail)
        !          10889: @findex rmail-quit
        !          10890:   You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and saves the
        !          10891: Rmail file and then switches to another buffer.  But there is no need to
        !          10892: `exit' formally.  If you switch from Rmail to editing in other buffers, and
        !          10893: never happen to switch back, you have exited.  Just make sure to save the
        !          10894: Rmail file eventually (like any other file you have changed).  @kbd{C-x s}
        !          10895: is a good enough way to do this (@pxref{Saving}).
        !          10896: 
        !          10897: @menu
        !          10898: * Scroll: Rmail Scrolling.   Scrolling through a message.
        !          10899: * Motion: Rmail Motion.      Moving to another message.
        !          10900: * Deletion: Rmail Deletion.  Deleting and expunging messages.
        !          10901: * Inbox: Rmail Inbox.        How mail gets into the Rmail file.
        !          10902: * Files: Rmail Files.        Using multiple Rmail files.
        !          10903: * Output: Rmail Output.             Copying message out to files.
        !          10904: * Labels: Rmail Labels.      Classifying messages by labeling them.
        !          10905: * Summary: Rmail Summary.    Summaries show brief info on many messages.
        !          10906: * Reply: Rmail Reply.        Sending replies to messages you are viewing.
        !          10907: * Editing: Rmail Editing.    Editing message text and headers in Rmail.
        !          10908: * Digest: Rmail Digest.      Extracting the messages from a digest message.
        !          10909: @end menu
        !          10910: 
        !          10911: @node Rmail Scrolling, Rmail Motion, Rmail, Rmail
        !          10912: @section Scrolling Within a Message
        !          10913: 
        !          10914:   When Rmail displays a message that does not fit on the screen, it is
        !          10915: necessary to scroll through it.  This could be done with @kbd{C-v}, @kbd{M-v}
        !          10916: and @kbd{M-<}, but in Rmail scrolling is so frequent that it deserves to be
        !          10917: easier to type.
        !          10918: 
        !          10919: @need 1800
        !          10920: @table @kbd
        !          10921: @item @key{SPC}
        !          10922: Scroll forward (@code{scroll-up}).
        !          10923: @item @key{DEL}
        !          10924: Scroll backward (@code{scroll-down}).
        !          10925: @item .
        !          10926: Scroll to start of message (@code{rmail-beginning-of-message}).
        !          10927: @end table
        !          10928: 
        !          10929: @kindex SPC (Rmail)
        !          10930: @kindex DEL (Rmail)
        !          10931:   Since the most common thing to do while reading a message is to scroll
        !          10932: through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of
        !          10933: @kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down}).
        !          10934: 
        !          10935: @kindex . (Rmail)
        !          10936: @findex rmail-beginning-of-message
        !          10937:   The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the
        !          10938: beginning of the selected message.  This is not quite the same as @kbd{M-<}:
        !          10939: for one thing, it does not set the mark; for another, it resets the buffer
        !          10940: boundaries to the current message if you have changed them.
        !          10941: 
        !          10942: @node Rmail Motion, Rmail Deletion, Rmail Scrolling, Rmail
        !          10943: @section Moving Among Messages
        !          10944: 
        !          10945:   The most basic thing to do with a message is to read it.  The way to do
        !          10946: this in Rmail is to make the message current.  You can make any message
        !          10947: current given its message number using the @kbd{j} command, but the usual
        !          10948: thing to do is to move sequentially through the file, since this is the
        !          10949: order of receipt of messages.  When you enter Rmail, you are positioned at
        !          10950: the first new message (new messages are those received since the previous
        !          10951: use of Rmail), or at the last message if there are no new messages this
        !          10952: time.  Move forward to see the other new messages; move backward to
        !          10953: reexamine old messages.
        !          10954: 
        !          10955: @table @kbd
        !          10956: @item n
        !          10957: Move to the next nondeleted message, skipping any intervening deleted
        !          10958: messages (@code{rmail-next-undeleted-message}).
        !          10959: @item p
        !          10960: @c !!! added @* to prevent overfull hbox
        !          10961: Move to the previous nondeleted message@*
        !          10962: (@code{rmail-previous-undeleted-message}).
        !          10963: @item M-n
        !          10964: @c !!! added @* to prevent overfull hbox
        !          10965: Move to the next message, including deleted messages@*
        !          10966: (@code{rmail-next-message}).
        !          10967: @item M-p
        !          10968: @c !!! added @* to prevent overfull hbox
        !          10969: Move to the previous message, including deleted messages@*
        !          10970: (@code{rmail-previous-message}).
        !          10971: @item j
        !          10972: Move to the first message.  With argument @var{n}, move to
        !          10973: message number @var{n} (@code{rmail-show-message}).
        !          10974: @item >
        !          10975: Move to the last message (@code{rmail-last-message}).
        !          10976: 
        !          10977: @item M-s @var{regexp} @key{RET}
        !          10978: Move to the next message containing a match for @var{regexp}
        !          10979: (@code{rmail-search}).  If @var{regexp} is empty, the last regexp used is
        !          10980: used again.
        !          10981: 
        !          10982: @item - M-s @var{regexp} @key{RET}
        !          10983: Move to the previous message containing a match for @var{regexp}.
        !          10984: If @var{regexp} is empty, the last regexp used is used again.
        !          10985: @end table
        !          10986: 
        !          10987: @kindex n (Rmail)
        !          10988: @kindex p (Rmail)
        !          10989: @kindex M-n (Rmail)
        !          10990: @kindex M-p (Rmail)
        !          10991: @findex rmail-next-undeleted-message
        !          10992: @findex rmail-previous-undeleted-message
        !          10993: @findex rmail-next-message
        !          10994: @findex rmail-previous-message
        !          10995:   @kbd{n} and @kbd{p} are the usual way of moving among messages in Rmail.  They
        !          10996: move through the messages sequentially, but skip over deleted messages,
        !          10997: which is usually what you want to do.  Their command definitions are named
        !          10998: @code{rmail-next-undeleted-message} and @code{rmail-previous-undeleted-message}.  If
        !          10999: you do not want to skip deleted messages---for example, if you want to move
        !          11000: to a message to undelete it---use the variants @kbd{M-n} and @kbd{M-p}
        !          11001: (@code{rmail-next-message} and @code{rmail-previous-message}).  A numeric
        !          11002: argument to any of these commands serves as a repeat count.@refill
        !          11003: 
        !          11004:   In Rmail, you can specify a numeric argument by typing the digits.
        !          11005: It is not necessary to type @kbd{C-u} first.
        !          11006: 
        !          11007: @kindex M-s (Rmail)
        !          11008: @findex rmail-search
        !          11009:   The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of search.  The
        !          11010: usual incremental search command @kbd{C-s} works in Rmail, but it searches
        !          11011: only within the current message.  The purpose of @kbd{M-s} is to search for
        !          11012: another message.  It reads a regular expression (@pxref{Regexps})
        !          11013: nonincrementally, then searches starting at the beginning of the following
        !          11014: message for a match.  The message containing the match is selected.
        !          11015: 
        !          11016:   To search backward in the file for another message, give @kbd{M-s} a
        !          11017: negative argument.  In Rmail this can be done with @kbd{- M-s}.
        !          11018: 
        !          11019:   It is also possible to search for a message based on labels.
        !          11020: @xref{Rmail Labels}.
        !          11021: 
        !          11022: @kindex j (Rmail)
        !          11023: @kindex > (Rmail)
        !          11024: @findex rmail-show-message
        !          11025: @findex rmail-last-message
        !          11026:   To move to a message specified by absolute message number, use @kbd{j}
        !          11027: (@code{rmail-show-message}) with the message number as argument.  With no
        !          11028: argument, @kbd{j} selects the first message.  @kbd{>} (@code{rmail-last-message}) selects
        !          11029: the last message.
        !          11030: 
        !          11031:   Each time Rmail selects a message, it calls (with no arguments) the
        !          11032: value of the variable @code{rmail-show-message-hook}, if that is
        !          11033: non-@code{nil}.
        !          11034: 
        !          11035: @node Rmail Deletion, Rmail Inbox, Rmail Motion, Rmail
        !          11036: @section Deleting Messages
        !          11037: 
        !          11038: @cindex deletion (Rmail)
        !          11039:   When you no longer need to keep a message, you can @dfn{delete} it.  This
        !          11040: flags it as ignorable, and some Rmail commands will pretend it is no longer
        !          11041: present; but it still has its place in the Rmail file, and still has its
        !          11042: message number.
        !          11043: 
        !          11044: @cindex expunging (Rmail)
        !          11045:   @dfn{Expunging} the Rmail file actually removes the deleted messages.
        !          11046: The remaining messages are renumbered consecutively.  Expunging is the only
        !          11047: action that changes the message number of any message, except for
        !          11048: undigestifying (@pxref{Rmail Digest}).
        !          11049: 
        !          11050: @table @kbd
        !          11051: @item d
        !          11052: Delete the current message, and move to the next nondeleted message
        !          11053: (@code{rmail-delete-forward}).
        !          11054: @item C-d
        !          11055: Delete the current message, and move to the previous nondeleted
        !          11056: message (@code{rmail-delete-backward}).
        !          11057: @item u
        !          11058: Undelete the current message, or move back to a deleted message and
        !          11059: undelete it (@code{rmail-undelete-previous-message}).
        !          11060: @item x
        !          11061: @itemx e
        !          11062: Expunge the Rmail file (@code{rmail-expunge}).  These two
        !          11063: commands are synonyms.
        !          11064: @end table
        !          11065: 
        !          11066: @kindex d (Rmail)
        !          11067: @kindex C-d (Rmail)
        !          11068: @findex rmail-delete-forward
        !          11069: @findex rmail-delete-backward
        !          11070:   There are two Rmail commands for deleting messages.  Both delete the
        !          11071: current message and select another message.  @kbd{d} (@code{rmail-delete-forward})
        !          11072: moves to the following message, skipping messages already deleted, while
        !          11073: @kbd{C-d} (@code{rmail-delete-backward}) moves to the previous nondeleted message.
        !          11074: If there is no nondeleted message to move to in the specified direction,
        !          11075: the message that was just deleted remains current.
        !          11076: 
        !          11077: @cindex undeletion (Rmail)
        !          11078: @kindex e (Rmail)
        !          11079: @findex rmail-expunge
        !          11080:   To make all the deleted messages finally vanish from the Rmail file,
        !          11081: type @kbd{e} (@code{rmail-expunge}).  Until you do this, you can still @dfn{undelete}
        !          11082: the deleted messages.
        !          11083: 
        !          11084: @kindex u (Rmail)
        !          11085: @findex rmail-undelete-previous-message
        !          11086:   To undelete, type
        !          11087: @kbd{u} (@code{rmail-undelete-previous-message}), which is designed to cancel the
        !          11088: effect of a @kbd{d} command (usually).  It undeletes the current message
        !          11089: if the current message is deleted.  Otherwise it moves backward to previous
        !          11090: messages until a deleted message is found, and undeletes that message.
        !          11091: 
        !          11092:   You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves
        !          11093: back to and undeletes the message that the @kbd{d} deleted.  But this does
        !          11094: not work when the @kbd{d} skips a few already-deleted messages that follow
        !          11095: the message being deleted; then the @kbd{u} command will undelete the last
        !          11096: of the messages that were skipped.  There is no clean way to avoid this
        !          11097: problem.  However, by repeating the @kbd{u} command, you can eventually get
        !          11098: back to the message that you intended to undelete.  You can also reach that
        !          11099: message with @kbd{M-p} commands and then type @kbd{u}.@refill
        !          11100: 
        !          11101:   A deleted message has the @samp{deleted} attribute, and as a result
        !          11102: @samp{deleted} appears in the mode line when the current message is
        !          11103: deleted.  In fact, deleting or undeleting a message is nothing more than
        !          11104: adding or removing this attribute.  @xref{Rmail Labels}.
        !          11105: 
        !          11106: @node Rmail Inbox, Rmail Files, Rmail Deletion, Rmail
        !          11107: @section Rmail Files and Inboxes
        !          11108: @cindex inbox file
        !          11109: 
        !          11110:   Unix places incoming mail for you in a file that we call your @dfn{inbox}.
        !          11111: When you start up Rmail, it copies the new messages from your inbox into
        !          11112: your primary mail file, an Rmail file, which also contains other messages
        !          11113: saved from previous Rmail sessions.  It is in this file that you actually
        !          11114: read the mail with Rmail.  This operation is called @dfn{getting new mail}.
        !          11115: It can be repeated at any time using the @kbd{g} key in Rmail.  The inbox
        !          11116: file name is @file{/usr/spool/mail/@var{username}} in Berkeley Unix,
        !          11117: @file{/usr/mail/@var{username}} in System V.
        !          11118: 
        !          11119:   There are two reasons for having separate Rmail files and inboxes.
        !          11120: 
        !          11121: @enumerate
        !          11122: @item
        !          11123: The format in which Unix delivers the mail in the inbox is not
        !          11124: adequate for Rmail mail storage.  It has no way to record attributes
        !          11125: (such as @samp{deleted}) or user-specified labels; it has no way to record
        !          11126: old headers and reformatted headers; it has no way to record cached
        !          11127: summary line information.
        !          11128: 
        !          11129: @item
        !          11130: It is very cumbersome to access an inbox file without danger of losing
        !          11131: mail, because it is necessary to interlock with mail delivery.
        !          11132: Moreover, different Unix systems use different interlocking
        !          11133: techniques.  The strategy of moving mail out of the inbox once and for
        !          11134: all into a separate Rmail file avoids the need for interlocking in all
        !          11135: the rest of Rmail, since only Rmail operates on the Rmail file.
        !          11136: @end enumerate
        !          11137: 
        !          11138:   When getting new mail, Rmail first copies the new mail from the inbox
        !          11139: file to the Rmail file; then it saves the Rmail file; then it deletes the
        !          11140: inbox file.  This way, a system crash may cause duplication of mail between
        !          11141: the inbox and the Rmail file, but cannot lose mail.
        !          11142: 
        !          11143:   Copying mail from an inbox in the system's mailer directory actually puts
        !          11144: it in an intermediate file @file{~/.newmail}.  This is because the
        !          11145: interlocking is done by a C program that copies to another file.
        !          11146: @file{~/.newmail} is deleted after mail merging is successful.  If there is
        !          11147: a crash at the wrong time, this file will continue to exist and will be
        !          11148: used as an inbox the next time you get new mail.
        !          11149: 
        !          11150: @node Rmail Files, Rmail Output, Rmail Inbox, Rmail
        !          11151: @section Multiple Mail Files
        !          11152: 
        !          11153:   Rmail operates by default on your @dfn{primary mail file}, which is named
        !          11154: @file{~/RMAIL} and receives your incoming mail from your system inbox file.
        !          11155: But you can also have other mail files and edit them with Rmail.  These
        !          11156: files can receive mail through their own inboxes, or you can move messages
        !          11157: into them by explicit command in Rmail (@pxref{Rmail Output}).
        !          11158: 
        !          11159: @table @kbd
        !          11160: @item i @var{file} @key{RET}
        !          11161: Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}).
        !          11162: 
        !          11163: @item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET}
        !          11164: Specify inbox file names for current Rmail file to get mail from.
        !          11165: 
        !          11166: @item g
        !          11167: Merge new mail from current Rmail file's inboxes
        !          11168: (@code{rmail-get-new-mail}).
        !          11169: 
        !          11170: @item C-u g @var{file}
        !          11171: Merge new mail from inbox file @var{file}.
        !          11172: @end table
        !          11173: 
        !          11174: @kindex i (Rmail)
        !          11175: @findex rmail-input
        !          11176:   To run Rmail on a file other than your primary mail file, you may use the
        !          11177: @kbd{i} (@code{rmail-input}) command in Rmail.  This visits the file, puts it in
        !          11178: Rmail mode, and then gets new mail from the file's inboxes if any.
        !          11179: You can also use @kbd{M-x rmail-input} even when not in Rmail.
        !          11180: 
        !          11181:   The file you read with @kbd{i} does not have to be in Rmail file format.
        !          11182: It could also be Unix mail format, or @code{mmdf} format; or it could
        !          11183: be a mixture of all three, as long as each message belongs to one of
        !          11184: the three formats.  Rmail recognizes all three and converts all the
        !          11185: messages to proper Rmail format before showing you the file.
        !          11186: 
        !          11187: @findex set-rmail-inbox-list
        !          11188:   Each Rmail file can contain a list of inbox file names; you can specify
        !          11189: this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files}
        !          11190: @key{RET}}.  The argument can contain any number of file names, separated
        !          11191: by commas.  It can also be empty, which specifies that this file should
        !          11192: have no inboxes.  Once a list of inboxes is specified, the Rmail file
        !          11193: remembers it permanently until it is explicitly changed.@refill
        !          11194: 
        !          11195: @kindex g (Rmail)
        !          11196: @findex rmail-get-new-mail
        !          11197:   If an Rmail file has inboxes, new mail is merged in from the inboxes when
        !          11198: the Rmail file is brought into Rmail, and when the @kbd{g} (@code{rmail-get-new-mail})
        !          11199: command is used.  If the Rmail file specifies no inboxes, then no new mail
        !          11200: is merged in at these times.  A special exception is made for your primary
        !          11201: mail file in using the standard system inbox for it if it does not specify
        !          11202: any.
        !          11203: 
        !          11204:   To merge mail from a file that is not the usual inbox, give the @kbd{g}
        !          11205: key a numeric argument, as in @kbd{C-u g}.  Then it reads a file name and
        !          11206: merges mail from that file.  The inbox file is not deleted or changed in
        !          11207: any way when @kbd{g} with an argument is used.  This is, therefore, a
        !          11208: general way of merging one file of messages into another.
        !          11209: 
        !          11210: @node Rmail Output, Rmail Labels, Rmail Files, Rmail
        !          11211: @section Copying Messages Out to Files
        !          11212: 
        !          11213: @table @kbd
        !          11214: @item o @var{file} @key{RET}
        !          11215: Append a copy of the current message to the file @var{file},
        !          11216: writing it in Rmail file format (@code{rmail-output-to-rmail-file}).
        !          11217: 
        !          11218: @item C-o @var{file} @key{RET}
        !          11219: Append a copy of the current message to the file @var{file},
        !          11220: writing it in Unix mail file format (@code{rmail-output}).
        !          11221: @end table
        !          11222: 
        !          11223: @kindex o (Rmail)
        !          11224: @findex rmail-output-to-rmail-file
        !          11225: @kindex C-o (Rmail)
        !          11226: @findex rmail-output
        !          11227:   If an Rmail file has no inboxes, how does it get anything in it?  By
        !          11228: explicit @kbd{o} commands.
        !          11229: 
        !          11230:   @kbd{o} (@code{rmail-output-to-rmail-file}) appends the current message
        !          11231: in Rmail format to the end of the specified file.  This is the best command
        !          11232: to use to move messages between Rmail files.  If the other Rmail file is
        !          11233: currently visited, the copying is done into the other file's Emacs buffer
        !          11234: instead.  You should eventually save it on disk.
        !          11235: 
        !          11236:   The @kbd{C-o} (@code{rmail-output}) command in Rmail appends a copy of the current
        !          11237: message to a specified file, in Unix mail file format.  This is useful for
        !          11238: moving messages into files to be read by other mail processors that do not
        !          11239: understand Rmail format.
        !          11240: 
        !          11241:   Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the
        !          11242: message the @samp{filed} attribute, so that @samp{filed} appears in the mode
        !          11243: line when such a message is current.
        !          11244: 
        !          11245:   Normally you should use only @kbd{o} to output messages to other Rmail
        !          11246: files, never @kbd{C-o}.  But it is also safe if you always use @kbd{C-o},
        !          11247: never @kbd{o}.  When a file is visited in Rmail, the last message is
        !          11248: checked, and if it is in Unix format, the entire file is scanned and all
        !          11249: Unix-format messages are converted to Rmail format.  (The reason for
        !          11250: checking the last message is that scanning the file is slow and most Rmail
        !          11251: files have only Rmail format messages.)  If you use @kbd{C-o} consistently,
        !          11252: the last message is sure to be in Unix format, so Rmail will convert all
        !          11253: messages properly.
        !          11254: 
        !          11255:   The case where you might want to use @kbd{C-o} always, instead of @kbd{o}
        !          11256: always, is when you or other users want to append mail to the same file
        !          11257: from other mail processors.  Other mail processors probably do not know
        !          11258: Rmail format but do know Unix format.
        !          11259: 
        !          11260:   In any case, always use @kbd{o} to add to an Rmail file that is being
        !          11261: visited in Rmail.  Adding messages with @kbd{C-o} to the actual disk file
        !          11262: will trigger a ``simultaneous editing'' warning when you ask to save the
        !          11263: Emacs buffer, and will be lost if you do save.
        !          11264: 
        !          11265: @node Rmail Labels, Rmail Summary, Rmail Output, Rmail
        !          11266: @section Labels
        !          11267: @cindex label (Rmail)
        !          11268: @cindex attribute (Rmail)
        !          11269: 
        !          11270:   Each message can have various @dfn{labels} assigned to it as a means of
        !          11271: classification.  A label has a name; different names mean different labels.
        !          11272: Any given label is either present or absent on a particular message.  A few
        !          11273: label names have standard meanings and are given to messages automatically
        !          11274: by Rmail when appropriate; these special labels are called @dfn{attributes}.
        !          11275: All other labels are assigned by the user.
        !          11276: 
        !          11277: @table @kbd
        !          11278: @item a @var{label} @key{RET}
        !          11279: Assign the label @var{label} to the current message (@code{rmail-add-label}).
        !          11280: @item k @var{label} @key{RET}
        !          11281: Remove the label @var{label} from the current message (@code{rmail-kill-label}).
        !          11282: @item C-M-n @var{labels} @key{RET}
        !          11283: Move to the next message that has one of the labels @var{labels}
        !          11284: (@code{rmail-next-labeled-message}).
        !          11285: @item C-M-p @var{labels} @key{RET}
        !          11286: Move to the previous message that has one of the labels @var{labels}
        !          11287: (@code{rmail-previous-labeled-message}).
        !          11288: @item C-M-l @var{labels} @key{RET}
        !          11289: Make a summary of all messages containing any of the labels @var{labels}
        !          11290: (@code{rmail-summary-by-labels}).
        !          11291: @end table
        !          11292: 
        !          11293: @noindent
        !          11294: Specifying an empty string for one these commands means to use the last
        !          11295: label specified for any of these commands.
        !          11296: 
        !          11297: @kindex a (Rmail)
        !          11298: @kindex k (rmail)
        !          11299: @findex rmail-add-label
        !          11300: @findex rmail-kill-label
        !          11301:   The @kbd{a} (@code{rmail-add-label}) and @kbd{k} (@code{rmail-kill-label}) commands allow
        !          11302: you to assign or remove any label on the current message.  If the @var{label}
        !          11303: argument is empty, it means to assign or remove the same label most
        !          11304: recently assigned or removed.
        !          11305: 
        !          11306:   Once you have given messages labels to classify them as you wish, there
        !          11307: are two ways to use the labels: in moving and in summaries.
        !          11308: 
        !          11309: @kindex C-M-n (Rmail)
        !          11310: @kindex C-M-p (Rmail)
        !          11311: @findex rmail-next-labeled-message
        !          11312: @findex rmail-previous-labeled-message
        !          11313:   The command @kbd{C-M-n @var{labels} @key{RET}}
        !          11314: (@code{rmail-next-labeled-message}) moves to the next message that has one
        !          11315: of the labels @var{labels}.  @var{labels} is one or more label names,
        !          11316: separated by commas.  @kbd{C-M-p} (@code{rmail-previous-labeled-message})
        !          11317: is similar, but moves backwards to previous messages.  A preceding numeric
        !          11318: argument to either one serves as a repeat count.@refill
        !          11319: 
        !          11320: @kindex C-M-l (Rmail)
        !          11321: @findex rmail-summary-by-labels
        !          11322:   The command @kbd{C-M-l @var{labels} @key{RET}}
        !          11323: (@code{rmail-summary-by-labels}) displays a summary containing only the
        !          11324: messages that have at least one of a specified set of messages.  The
        !          11325: argument @var{labels} is one or more label names, separated by commas.
        !          11326: @xref{Rmail Summary}, for information on summaries.@refill
        !          11327: 
        !          11328:   If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or @kbd{C-M-l} is empty, it means
        !          11329: to use the last set of labels specified for any of these commands.
        !          11330: 
        !          11331:   Some labels such as @samp{deleted} and @samp{filed} have built-in meanings and
        !          11332: are assigned to or removed from messages automatically at appropriate
        !          11333: times; these labels are called @dfn{attributes}.  Here is a list of Rmail
        !          11334: attributes:
        !          11335: 
        !          11336: @table @samp
        !          11337: @item unseen
        !          11338: Means the message has never been current.  Assigned to messages when
        !          11339: they come from an inbox file, and removed when a message is made
        !          11340: current.
        !          11341: @item deleted
        !          11342: Means the message is deleted.  Assigned by deletion commands and
        !          11343: removed by undeletion commands (@pxref{Rmail Deletion}).
        !          11344: @item filed
        !          11345: Means the message has been copied to some other file.  Assigned by the
        !          11346: file output commands (@pxref{Rmail Files}).
        !          11347: @item answered
        !          11348: Means you have mailed an answer to the message.  Assigned by the @kbd{r}
        !          11349: command (@code{rmail-reply}).  @xref{Rmail Reply}.
        !          11350: @item forwarded
        !          11351: Means you have forwarded the message to other users.  Assigned by the
        !          11352: @kbd{f} command (@code{rmail-forward}).  @xref{Rmail Reply}.
        !          11353: @item edited
        !          11354: Means you have edited the text of the message within Rmail.
        !          11355: @xref{Rmail Editing}.
        !          11356: @end table
        !          11357: 
        !          11358:   All other labels are assigned or removed only by the user, and it is up
        !          11359: to the user to decide what they mean.
        !          11360: 
        !          11361: @node Rmail Summary, Rmail Reply, Rmail Labels, Rmail
        !          11362: @section Summaries
        !          11363: @cindex summary (Rmail)
        !          11364: 
        !          11365:   A @dfn{summary} is a buffer containing one line per message that Rmail
        !          11366: can make and display to give you an overview of the mail in an Rmail file.
        !          11367: Each line shows the message number, the sender, the labels, and the
        !          11368: subject.  When the summary buffer is selected, various commands can be used
        !          11369: to select messages by moving in the summary buffer, or delete or undelete
        !          11370: messages.
        !          11371: 
        !          11372:   A summary buffer applies to a single Rmail file only; if you are
        !          11373: editing multiple Rmail files, they have separate summary buffers.  The
        !          11374: summary buffer name is made by appending @samp{-summary} to the Rmail buffer's
        !          11375: name.  Only one summary buffer will be displayed at a time unless you make
        !          11376: several windows and select the summary buffers by hand.
        !          11377: 
        !          11378: @menu
        !          11379: * Rmail Make Summary::  Making various sorts of summaries.
        !          11380: * Rmail Summary Edit::  Manipulating messages from the summary.
        !          11381: @end menu
        !          11382: 
        !          11383: @node Rmail Make Summary, Rmail Summary Edit, Rmail Summary, Rmail Summary
        !          11384: @subsection Making Summaries
        !          11385: 
        !          11386:   Here are the commands to create a summary for the current Rmail file.
        !          11387: Summaries do not update automatically; to make an updated summary, you
        !          11388: must use one of these commands again.
        !          11389: 
        !          11390: @table @kbd
        !          11391: @item h
        !          11392: @itemx C-M-h
        !          11393: Summarize all messages (@code{rmail-summary}).
        !          11394: @item l @var{labels} @key{RET}
        !          11395: @itemx C-M-l @var{labels} @key{RET}
        !          11396: Summarize message that have one or more of the specified labels
        !          11397: (@code{rmail-summary-by-labels}).
        !          11398: @item C-M-r @var{rcpts} @key{RET}
        !          11399: Summarize messages that have one or more of the specified recipients
        !          11400: (@code{rmail-summary-by-recipients}).
        !          11401: @end table
        !          11402: 
        !          11403: @kindex h (Rmail)
        !          11404: @findex rmail-summary
        !          11405:   The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer
        !          11406: for the current Rmail file with a summary of all the messages in the file.
        !          11407: It then displays and selects the summary buffer in another window.
        !          11408: 
        !          11409: @kindex l (Rmail)
        !          11410: @kindex C-M-l (Rmail)
        !          11411: @findex rmail-summary-by-labels
        !          11412:   @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes
        !          11413: a partial summary mentioning only the messages that have one or more of the
        !          11414: labels @var{labels}.  @var{labels} should contain label names separated by
        !          11415: commas.@refill
        !          11416: 
        !          11417: @kindex C-M-r (Rmail)
        !          11418: @findex rmail-summary-by-recipients
        !          11419:   @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients})
        !          11420: makes a partial summary mentioning only the messages that have one or more
        !          11421: of the recipients @var{rcpts}.  @var{rcpts} should contain mailing
        !          11422: addresses separated by commas.@refill
        !          11423: 
        !          11424:   Note that there is only one summary buffer for any Rmail file; making one
        !          11425: kind of summary discards any previously made summary.
        !          11426: 
        !          11427: @node Rmail Summary Edit,, Rmail Make Summary, Rmail Summary
        !          11428: @subsection Editing in Summaries
        !          11429: @cindex Rmail Summary mode
        !          11430: @cindex summaries in Rmail
        !          11431: 
        !          11432:   Summary buffers are given the major mode Rmail Summary mode, which
        !          11433: provides the following special commands:
        !          11434: 
        !          11435: @table @kbd
        !          11436: @item j
        !          11437: Select the message described by the line that point is on
        !          11438: (@code{rmail-summary-goto-msg}).
        !          11439: @item C-n
        !          11440: Move to next line and select its message in Rmail
        !          11441: (@code{rmail-summary-next-all}).
        !          11442: @item C-p
        !          11443: Move to previous line and select its message
        !          11444: (@code{rmail-summary-previous-all}).
        !          11445: @item n
        !          11446: Move to next line, skipping lines saying `deleted', and select its
        !          11447: message (@code{rmail-summary-next-msg}).
        !          11448: @item p
        !          11449: Move to previous line, skipping lines saying `deleted', and select
        !          11450: its message (@code{rmail-summary-previous-msg}).
        !          11451: @c !!! following generates acceptable underfull hbox
        !          11452: @item d
        !          11453: Delete the current line's message, then do like @kbd{n}
        !          11454: (@code{rmail-summary-delete-forward}).
        !          11455: @item u
        !          11456: Undelete and select this message or the previous deleted message in
        !          11457: the summary (@code{rmail-summary-undelete}).
        !          11458: @item @key{SPC}
        !          11459: Scroll the other window (presumably Rmail) forward
        !          11460: (@code{rmail-summary-scroll-msg-up}).
        !          11461: @item @key{DEL}
        !          11462: Scroll the other window backward (@code{rmail-summary-scroll-msg-down}).
        !          11463: @item x
        !          11464: Kill the summary window (@code{rmail-summary-exit}).
        !          11465: @item q
        !          11466: Exit Rmail (@code{rmail-summary-quit}).
        !          11467: @end table
        !          11468: 
        !          11469: @kindex C-n (Rmail summary)
        !          11470: @kindex C-p (Rmail summary)
        !          11471: @findex rmail-summary-next-all
        !          11472: @findex rmail-summary-previous-all
        !          11473:   The keys @kbd{C-n} and @kbd{C-p} are modified in Rmail Summary mode so that in
        !          11474: addition to moving point in the summary buffer they also cause the line's
        !          11475: message to become current in the associated Rmail buffer.  That buffer is
        !          11476: also made visible in another window if it is not already so.
        !          11477: 
        !          11478: @kindex n (Rmail summary)
        !          11479: @kindex p (Rmail summary)
        !          11480: @findex rmail-summary-next-msg
        !          11481: @findex rmail-summary-previous-msg
        !          11482:   @kbd{n} and @kbd{p} are similar to @kbd{C-n} and @kbd{C-p}, but skip
        !          11483: lines that say `message deleted'.  They are like the @kbd{n} and @kbd{p}
        !          11484: keys of Rmail itself.  Note, however, that in a partial summary these
        !          11485: commands move only among the message listed in the summary.@refill
        !          11486: 
        !          11487: @kindex j (Rmail summary)
        !          11488: @findex rmail-summary-goto-msg
        !          11489:   The other Emacs cursor motion commands are not changed in Rmail Summary
        !          11490: mode, so it is easy to get the point on a line whose message is not
        !          11491: selected in Rmail.  This can also happen if you switch to the Rmail window
        !          11492: and switch messages there.  To get the Rmail buffer back in sync with the
        !          11493: summary, use the @kbd{j} (@code{rmail-summary-goto-msg}) command, which selects
        !          11494: in Rmail the message of the current summary line.
        !          11495: 
        !          11496: @kindex d (Rmail summary)
        !          11497: @kindex u (Rmail summary)
        !          11498: @findex rmail-summary-delete-forward
        !          11499: @findex rmail-summary-undelete
        !          11500:   Deletion and undeletion can also be done from the summary buffer.  They
        !          11501: always work based on where point is located in the summary buffer, ignoring
        !          11502: which message is selected in Rmail.  @kbd{d} (@code{rmail-summary-delete-forward})
        !          11503: deletes the current line's message, then moves to the next line whose
        !          11504: message is not deleted and selects that message.  The inverse of this is
        !          11505: @kbd{u} (@code{rmail-summary-undelete}), which moves back (if necessary) to a line
        !          11506: whose message is deleted, undeletes that message, and selects it in Rmail.
        !          11507: 
        !          11508: @kindex SPC (Rmail summary)
        !          11509: @kindex DEL (Rmail summary)
        !          11510: @findex rmail-summary-scroll-msg-down
        !          11511: @findex rmail-summary-scroll-msg-up
        !          11512:   When moving through messages with the summary buffer, it is convenient to
        !          11513: be able to scroll the message while remaining in the summary window.
        !          11514: The commands @key{SPC} (@code{rmail-summary-scroll-msg-up}) and @key{DEL}
        !          11515: (@code{rmail-summary-scroll-msg-down}) do this.  They scroll the message just
        !          11516: as those same keys do when the Rmail buffer is selected.@refill
        !          11517: 
        !          11518: @kindex x (Rmail summary)
        !          11519: @findex rmail-summary-exit
        !          11520:   When you are finished using the summary, type @kbd{x} (@code{rmail-summary-exit})
        !          11521: to kill the summary buffer's window.
        !          11522: 
        !          11523: @kindex q (Rmail summary)
        !          11524: @findex rmail-summary-quit
        !          11525:   You can also exit Rmail while in the summary.  @kbd{q} (@code{rmail-summary-quit})
        !          11526: kills the summary window, then saves the Rmail file and switches to another
        !          11527: buffer.
        !          11528: 
        !          11529: @node Rmail Reply, Rmail Editing, Rmail Summary, Rmail
        !          11530: @section Sending Replies
        !          11531: 
        !          11532:   Rmail has several commands that use Mail mode to send outgoing mail.
        !          11533: @xref{Sending Mail}, for information on using Mail mode.  What are
        !          11534: documented here are the special commands of Rmail for entering Mail mode.
        !          11535: Note that the usual keys for sending mail, @kbd{C-x m} and @kbd{C-x 4 m},
        !          11536: are available in Rmail mode and work just as they usually do.@refill
        !          11537: 
        !          11538: @table @kbd
        !          11539: @item m
        !          11540: Send a message (@code{rmail-mail}).
        !          11541: @c !!! following generates acceptable underfull hbox
        !          11542: @item c
        !          11543: Continue editing already started outgoing message (@code{rmail-continue}).
        !          11544: @item r
        !          11545: Send a reply to the current Rmail message (@code{rmail-reply}).
        !          11546: @item f
        !          11547: Forward current message to other users (@code{rmail-forward}).
        !          11548: @end table
        !          11549: 
        !          11550: @kindex r (Rmail)
        !          11551: @findex rmail-reply
        !          11552: @vindex rmail-dont-reply-to
        !          11553: @cindex reply to a message
        !          11554:   The most common reason to send a message while in Rmail is to reply to
        !          11555: the message you are reading.  To do this, type @kbd{r}
        !          11556: (@code{rmail-reply}).  This displays the @samp{*mail*} buffer in another
        !          11557: window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject},
        !          11558: @samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the
        !          11559: message being replied to.  The @samp{To} field is given the sender of that
        !          11560: message, and the @samp{CC} gets all the recipients of that message (but
        !          11561: recipients that match elements of the list @code{rmail-dont-reply-to} are
        !          11562: omitted; by default, this list contains your own mailing address).@refill
        !          11563: 
        !          11564:   If you don't want to include the other recipients in the @samp{cc} field,
        !          11565: you can use a prefix argument to the @kbd{r} command.  In Rmail, you can 
        !          11566: do this with @w{@kbd{1 r}}.
        !          11567: 
        !          11568:   Once you have initialized the @samp{*mail*} buffer this way, sending the
        !          11569: mail goes as usual (@pxref{Sending Mail}).  You can edit the presupplied
        !          11570: header fields if they are not right for you.
        !          11571: 
        !          11572: @kindex C-c C-y (Mail mode)
        !          11573: @findex mail-yank-original
        !          11574:   One additional Mail mode command is available when mailing is invoked
        !          11575: from Rmail: @kbd{C-c C-y} (@code{mail-yank-original}) inserts into the outgoing
        !          11576: message a copy of the current Rmail message; normally this is the message
        !          11577: you are replying to, but you can also switch to the Rmail buffer, select a
        !          11578: different message, switch back, and yank new current message.  Normally the
        !          11579: yanked message is indented four spaces and has most header fields deleted
        !          11580: from it; an argument to @kbd{C-c C-y} specifies the amount to indent, and
        !          11581: @kbd{C-u C-c C-y} does not indent at all and does not delete any header
        !          11582: fields.@refill
        !          11583: 
        !          11584: @kindex f (Rmail)
        !          11585: @findex rmail-forward
        !          11586: @cindex forward a message
        !          11587:   Another frequent reason to send mail in Rmail is to forward the current
        !          11588: message to other users.  @kbd{f} (@code{rmail-forward}) makes this easy by
        !          11589: preinitializing the @samp{*mail*} buffer with the current message as the
        !          11590: text, and a subject designating a forwarded message.  All you have to do is
        !          11591: fill in the recipients and send.@refill
        !          11592: 
        !          11593: @kindex m (Rmail)
        !          11594: @findex rmail-mail
        !          11595:   The @kbd{m} (@code{rmail-mail}) command is used to start editing an
        !          11596: outgoing message that is not a reply.  It leaves the header fields empty.
        !          11597: Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer
        !          11598: accessible for @kbd{C-c y}, just as @kbd{r} does.  Thus, @kbd{m} can be
        !          11599: used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f}
        !          11600: can do.@refill
        !          11601: 
        !          11602: @kindex c (Rmail)
        !          11603: @findex rmail-continue
        !          11604:   The @kbd{c} (@code{rmail-continue}) command resumes editing the
        !          11605: @samp{*mail*} buffer, to finish editing an outgoing message you were
        !          11606: already composing, or to alter a message you have sent.@refill
        !          11607: 
        !          11608: @node Rmail Editing, Rmail Digest, Rmail Reply, Rmail
        !          11609: @section Editing Within a Message
        !          11610: 
        !          11611:   Rmail mode provides a few special commands for moving within and editing
        !          11612: the current message.  In addition, the usual Emacs commands are available
        !          11613: (except for a few, such as @kbd{C-M-n} and @kbd{C-M-h}, that are redefined by Rmail for
        !          11614: other purposes).  However, the Rmail buffer is normally read-only, and to
        !          11615: alter it you must use the Rmail command @kbd{w} described below.
        !          11616: 
        !          11617: @table @kbd
        !          11618: @item t
        !          11619: Toggle display of original headers (@code{rmail-toggle-headers}).
        !          11620: @item w
        !          11621: Edit current message (@code{rmail-edit-current-message}).
        !          11622: @end table
        !          11623: 
        !          11624: @kindex t (Rmail)
        !          11625: @findex rmail-toggle-header
        !          11626: @vindex rmail-ignored-headers
        !          11627:   Rmail reformats the header of each message before displaying it.
        !          11628: Normally this involves deleting most header fields, on the grounds that
        !          11629: they are not interesting.  The variable @code{rmail-ignored-headers} should
        !          11630: contain a regexp that matches the header fields to discard in this way.
        !          11631: The original headers are saved permanently, and to see what they look like,
        !          11632: use the @kbd{t} (@code{rmail-toggle-headers}) command.  This discards the reformatted
        !          11633: headers of the current message and displays it with the original headers.
        !          11634: Repeating @kbd{t} reformats the message again.  Selecting the message again
        !          11635: also reformats.
        !          11636: 
        !          11637: @kindex w (Rmail)
        !          11638: @findex rmail-edit-current-message
        !          11639:   The Rmail buffer is normally read-only, and most of the characters you
        !          11640: would type to modify it (including most letters) are redefined as Rmail
        !          11641: commands.  This is usually not a problem since it is rare to want to change
        !          11642: the text of a message.  When you do want to do this, the way is to type
        !          11643: @kbd{w} (@code{rmail-edit-current-message}), which changes from Rmail mode into
        !          11644: Rmail Edit mode, another major mode which is nearly the same as Text mode.
        !          11645: The mode line illustrates this change.
        !          11646: 
        !          11647:   In Rmail Edit mode, letters insert themselves as usual and the Rmail
        !          11648: commands are not available.  When you are finished editing the message and
        !          11649: are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to
        !          11650: Rmail mode.  Alternatively, you can return to Rmail mode but cancel all the
        !          11651: editing that you have done by typing @kbd{C-c C-]}.
        !          11652: 
        !          11653: @vindex rmail-edit-mode-hook
        !          11654:   Entering Rmail Edit mode calls with no arguments the value of the variable
        !          11655: @code{text-mode-hook}, if that value exists and is not @code{nil}; then it
        !          11656: does the same with the variable @code{rmail-edit-mode-hook}.  It adds the
        !          11657: attribute @samp{edited} to the message.
        !          11658: 
        !          11659: @node Rmail Digest,, Rmail Editing, Rmail
        !          11660: @section Digest Messages
        !          11661: @cindex digest message
        !          11662: @cindex undigestify
        !          11663: 
        !          11664:   A @dfn{digest message} is a message which exists to contain and carry
        !          11665: several other messages.  Digests are used on moderated mailing lists; all
        !          11666: the messages that arrive for the list during a period of time such as one
        !          11667: day are put inside a single digest which is then sent to the subscribers.
        !          11668: Transmitting the single digest uses much less computer time than
        !          11669: transmitting the individual messages even though the total size is the
        !          11670: same, because the per-message overhead in network mail transmission is
        !          11671: considerable.
        !          11672: 
        !          11673: @findex undigestify-rmail-message
        !          11674:   When you receive a digest message, the most convenient way to read it is
        !          11675: to @dfn{undigestify} it: to turn it back into many individual messages.
        !          11676: Then you can read and delete the individual messages as it suits you.
        !          11677: 
        !          11678:   To undigestify a message, select it and then type @kbd{M-x
        !          11679: undigestify-rmail-message}.  This copies each submessage as a separate
        !          11680: Rmail message and inserts them all following the digest.  The digest
        !          11681: message itself is flagged as deleted.
        !          11682: 
        !          11683: @iftex
        !          11684: @chapter Miscellaneous Commands
        !          11685: 
        !          11686:   This chapter contains several brief topics that do not fit anywhere else.
        !          11687: 
        !          11688: @end iftex
        !          11689: @node Recursive Edit, Narrowing, Rmail, Top
        !          11690: @section Recursive Editing Levels
        !          11691: @cindex recursive editing level
        !          11692: @cindex editing level, recursive
        !          11693: 
        !          11694:   A @dfn{recursive edit} is a situation in which you are using Emacs
        !          11695: commands to perform arbitrary editing while in the middle of another Emacs
        !          11696: command.  For example, when you type @kbd{C-r} inside of a @code{query-replace},
        !          11697: you enter a recursive edit in which you can change the current buffer.  On
        !          11698: exiting from the recursive edit, you go back to the @code{query-replace}.
        !          11699: 
        !          11700: @kindex C-M-c
        !          11701: @findex exit-recursive-edit
        !          11702: @cindex exiting
        !          11703:   @dfn{Exiting} the recursive edit means returning to the unfinished
        !          11704: command, which continues execution.  For example, exiting the recursive
        !          11705: edit requested by @kbd{C-r} in @code{query-replace} causes query replacing
        !          11706: to resume.  Exiting is done with @kbd{C-M-c} (@code{exit-recursive-edit}).
        !          11707: 
        !          11708: @kindex C-]
        !          11709: @findex abort-recursive-edit
        !          11710:   You can also @dfn{abort} the recursive edit.  This is like exiting, but
        !          11711: also quits the unfinished command immediately.  Use the command @kbd{C-]}
        !          11712: (@code{abort-recursive-edit}) for this.  @xref{Quitting}.
        !          11713: 
        !          11714:   The mode line shows you when you are in a recursive edit by displaying
        !          11715: square brackets around the parentheses that always surround the major and
        !          11716: minor mode names.  Every window's mode line shows this, in the same way,
        !          11717: since being in a recursive edit is true of Emacs as a whole rather than
        !          11718: any particular buffer.
        !          11719: 
        !          11720: @findex top-level
        !          11721:   It is possible to be in recursive edits within recursive edits.  For
        !          11722: example, after typing @kbd{C-r} in a @code{query-replace}, you might type a
        !          11723: command that entered the debugger.  In such circumstances, two or more sets
        !          11724: of square brackets appear in the mode line.  Exiting the inner recursive
        !          11725: edit (such as, with the debugger @kbd{c} command) would resume the command
        !          11726: where it called the debugger.  After the end of this command, you would be
        !          11727: able to exit the first recursive edit.  Aborting also gets out of only one
        !          11728: level of recursive edit; it returns immediately to the command level of the
        !          11729: previous recursive edit.  So you could immediately abort that one too.
        !          11730: 
        !          11731:   Alternatively, the command @kbd{M-x top-level} aborts all levels of
        !          11732: recursive edits, returning immediately to the top level command reader.
        !          11733: 
        !          11734:   The text being edited inside the recursive edit need not be the same text
        !          11735: that you were editing at top level.  It depends on what the recursive edit
        !          11736: is for.  If the command that invokes the recursive edit selects a different
        !          11737: buffer first, that is the buffer you will edit recursively.  In any case,
        !          11738: you can switch buffers within the recursive edit in the normal manner (as
        !          11739: long as the buffer-switching keys have not been rebound).  You could
        !          11740: probably do all the rest of your editing inside the recursive edit,
        !          11741: visiting files and all.  But this could have surprising effects (such as
        !          11742: stack overflow) from time to time.  So remember to exit or abort the
        !          11743: recursive edit when you no longer need it.
        !          11744: 
        !          11745:   In general, GNU Emacs tries to avoid using recursive edits.  It is
        !          11746: usually preferable to allow the user to switch among the possible editing
        !          11747: modes in any order he likes.  With recursive edits, the only way to get to
        !          11748: another state is to go ``back'' to the state that the recursive edit was
        !          11749: invoked from.
        !          11750: 
        !          11751: @node Narrowing, Sorting, Recursive Edit, Top
        !          11752: @section Narrowing
        !          11753: @cindex widening
        !          11754: @cindex restriction
        !          11755: @cindex narrowing
        !          11756: 
        !          11757:   @dfn{Narrowing} means focusing in on some portion of the buffer, making
        !          11758: the rest temporarily invisible and inaccessible.  Cancelling the narrowing,
        !          11759: and making the entire buffer once again visible, is called @dfn{widening}.
        !          11760: The amount of narrowing in effect in a buffer at any time is called the
        !          11761: buffer's @dfn{restriction}.
        !          11762: 
        !          11763: @c WideCommands
        !          11764: @table @kbd
        !          11765: @item C-x n
        !          11766: Narrow down to between point and mark (@code{narrow-to-region}).
        !          11767: @item C-x w
        !          11768: Widen to make the entire buffer visible again (@code{widen}).
        !          11769: @end table
        !          11770: 
        !          11771:   When you have narrowed down to a part of the buffer, that part appears to
        !          11772: be all there is.  You can't see the rest, you can't move into it (motion
        !          11773: commands won't go outside the visible part), you can't change it in any
        !          11774: way.  However, it is not gone, and if you save the file all the invisible
        !          11775: text will be saved.  In addition to sometimes making it easier to
        !          11776: concentrate on a single subroutine or paragraph by eliminating clutter,
        !          11777: narrowing can be used to restrict the range of operation of a replace
        !          11778: command or repeating keyboard macro.  The word @samp{Narrow} appears in the
        !          11779: mode line whenever narrowing is in effect.
        !          11780: 
        !          11781: @kindex C-x n
        !          11782: @findex narrow-to-region
        !          11783:   The primary narrowing command is @kbd{C-x n} (@code{narrow-to-region}).
        !          11784: It sets the current buffer's restrictions so that the text in the current
        !          11785: region remains visible but all text before the region or after the region
        !          11786: is invisible.  Point and mark do not change.
        !          11787: 
        !          11788:   Because narrowing can easily confuse users who do not understand it,
        !          11789: @code{narrow-to-region} is normally a disabled command.  Attempting to use
        !          11790: this command asks for confirmation and gives you the option of enabling it;
        !          11791: once you enable the command, confirmation will no longer be required for
        !          11792: it.  @xref{Disabling}.
        !          11793: 
        !          11794: @kindex C-x w
        !          11795: @findex widen
        !          11796:   The way to undo narrowing is to widen with @kbd{C-x w} (@code{widen}).
        !          11797: This makes all text in the buffer accessible again.
        !          11798: 
        !          11799:   You can get information on what part of the buffer you are narrowed down
        !          11800: to using the @kbd{C-x =} command.  @xref{Position Info}.
        !          11801: 
        !          11802: @node Sorting, Shell, Narrowing, Top
        !          11803: @section Sorting Text
        !          11804: @cindex sorting
        !          11805: 
        !          11806:   Emacs provides several commands for sorting text in the buffer.  All
        !          11807: operate on the contents of the region (the text between point and the
        !          11808: mark).  They divide the text of the region into many @dfn{sort records},
        !          11809: identify a @dfn{sort key} for each record, and then reorder the records
        !          11810: into the order determined by the sort keys.  The records are ordered so
        !          11811: that their keys are in alphabetical order, or, for numeric sorting, in
        !          11812: numeric order.  In alphabetic sorting, all upper case letters `A' through
        !          11813: `Z' come before lower case `a', in accord with the @sc{ascii} character
        !          11814: sequence.
        !          11815: 
        !          11816:   The various sort commands differ in how they divide the text into sort
        !          11817: records and in which part of each record is used as the sort key.  Most of
        !          11818: the commands make each line a separate sort record, but some commands use
        !          11819: paragraphs or pages as sort records.  Most of the sort commands use each
        !          11820: entire sort record as its own sort key, but some use only a portion of the
        !          11821: record as the sort key.
        !          11822: 
        !          11823: @findex sort-lines
        !          11824: @findex sort-paragraphs
        !          11825: @findex sort-pages
        !          11826: @findex sort-fields
        !          11827: @findex sort-numeric-fields
        !          11828: @table @kbd
        !          11829: @item M-x sort-lines
        !          11830: Divide the region into lines, and sort by comparing the entire
        !          11831: text of a line.  A prefix argument means sort into descending order.
        !          11832: 
        !          11833: @item M-x sort-paragraphs
        !          11834: Divide the region into paragraphs, and sort by comparing the entire
        !          11835: text of a paragraph (except for leading blank lines).  A prefix
        !          11836: argument means sort into descending order.
        !          11837: 
        !          11838: @item M-x sort-pages
        !          11839: Divide the region into pages, and sort by comparing the entire
        !          11840: text of a page (except for leading blank lines).  A prefix
        !          11841: argument means sort into descending order.
        !          11842: 
        !          11843: @item M-x sort-fields
        !          11844: Divide the region into lines, and sort by comparing the contents of
        !          11845: one field in each line.  Fields are defined as separated by
        !          11846: whitespace, so the first run of consecutive non-whitespace characters
        !          11847: in a line constitutes field 1, the second such run constitutes field
        !          11848: 2, etc.
        !          11849: 
        !          11850: You specify which field to sort by with a numeric argument: 1 to sort
        !          11851: by field 1, etc.  A negative argument means sort into descending
        !          11852: order.  Thus, minus 2 means sort by field 2 in reverse-alphabetical
        !          11853: order.
        !          11854: 
        !          11855: If two lines are equal in the field being compared, their relative order
        !          11856: in the text is not changed.  This enables you to sort by multiple keys:
        !          11857: sort first by the least significant key, then by the next-to-least
        !          11858: key, and so on, ending with the most important key.
        !          11859: 
        !          11860: @item M-x sort-numeric-fields
        !          11861: Like @kbd{M-x sort-fields} except the specified field is converted
        !          11862: to a number for each line, and the numbers are compared.  @samp{10}
        !          11863: comes before @samp{2} when considered as text, but after it when
        !          11864: considered as a number.
        !          11865: 
        !          11866: @item M-x sort-columns
        !          11867: Like @kbd{M-x sort-fields} except that the text within each line
        !          11868: used for comparison comes from a fixed range of columns.  See below
        !          11869: for an explanation.
        !          11870: @end table
        !          11871: 
        !          11872: For example, if the buffer contains
        !          11873: 
        !          11874: @smallexample
        !          11875: On systems where clash detection (locking of files being edited) is
        !          11876: implemented, Emacs also checks the first time you modify a buffer
        !          11877: whether the file has changed on disk since it was last visited or
        !          11878: saved.  If it has, you are asked to confirm that you want to change
        !          11879: the buffer.
        !          11880: @end smallexample
        !          11881: 
        !          11882: @noindent
        !          11883: then if you apply @kbd{M-x sort-lines} to the entire buffer you get
        !          11884: 
        !          11885: @smallexample
        !          11886: On systems where clash detection (locking of files being edited) is
        !          11887: implemented, Emacs also checks the first time you modify a buffer
        !          11888: saved.  If it has, you are asked to confirm that you want to change
        !          11889: the buffer.
        !          11890: whether the file has changed on disk since it was last visited or
        !          11891: @end smallexample
        !          11892: 
        !          11893: @noindent
        !          11894: where the upper case `O' comes before all lower case letters.  If you apply
        !          11895: instead @kbd{C-u 2 M-x sort-fields} you get
        !          11896: 
        !          11897: @smallexample
        !          11898: implemented, Emacs also checks the first time you modify a buffer
        !          11899: saved.  If it has, you are asked to confirm that you want to change
        !          11900: the buffer.
        !          11901: On systems where clash detection (locking of files being edited) is
        !          11902: whether the file has changed on disk since it was last visited or
        !          11903: @end smallexample
        !          11904: 
        !          11905: @noindent
        !          11906: where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer},
        !          11907: @samp{systems} and @samp{the}.@refill
        !          11908: 
        !          11909: @findex sort-columns
        !          11910:   @kbd{M-x sort-columns} requires more explanation.  You specify the
        !          11911: columns by putting point at one of the columns and the mark at the other
        !          11912: column.  Because this means you cannot put point or the mark at the
        !          11913: beginning of the first line to sort, this command uses an unusual
        !          11914: definition of `region': all of the line point is in is considered part of
        !          11915: the region, and so is all of the line the mark is in.
        !          11916: 
        !          11917:   For example, to sort a table by information found in columns 10 to 15,
        !          11918: you could put the mark on column 10 in the first line of the table, and
        !          11919: point on column 15 in the last line of the table, and then use this command.
        !          11920: Or you could put the mark on column 15 in the first line and point on
        !          11921: column 10 in the last line.
        !          11922: 
        !          11923:   This can be thought of as sorting the rectangle specified by point and
        !          11924: the mark, except that the text on each line to the left or right of the
        !          11925: rectangle moves along with the text inside the rectangle.
        !          11926: @xref{Rectangles}.
        !          11927: 
        !          11928: @node Shell, Hardcopy, Sorting, Top
        !          11929: @section Running Shell Commands from Emacs
        !          11930: @cindex subshell
        !          11931: @cindex shell commands
        !          11932: 
        !          11933:   Emacs has commands for passing single command lines to inferior shell
        !          11934: processes; it can also run a shell interactively with input and output to
        !          11935: an Emacs buffer @samp{*shell*}.
        !          11936: 
        !          11937: @table @kbd
        !          11938: @item M-!
        !          11939: Run a specified shell command line and display the output
        !          11940: (@code{shell-command}).
        !          11941: @item M-|
        !          11942: Run a specified shell command line with region contents as input;
        !          11943: optionally replace the region with the output
        !          11944: (@code{shell-command-on-region}).
        !          11945: @item M-x shell
        !          11946: Run a subshell with input and output through an Emacs buffer.
        !          11947: You can then give commands interactively.
        !          11948: @end table
        !          11949: 
        !          11950: @menu
        !          11951: * Single Shell::         How to run one shell command and return.
        !          11952: * Interactive Shell::    Permanent shell taking input via Emacs.
        !          11953: * Shell Mode::           Special Emacs commands used with permanent shell.
        !          11954: @end menu
        !          11955: 
        !          11956: @node Single Shell, Interactive Shell, Shell, Shell
        !          11957: @subsection Single Shell Commands
        !          11958: 
        !          11959: @kindex M-!
        !          11960: @findex shell-command
        !          11961:   @kbd{M-!} (@code{shell-command}) reads a line of text using the
        !          11962: minibuffer and creates an inferior shell to execute the line as a command.
        !          11963: Standard input from the command comes from the null device.  If the shell
        !          11964: command produces any output, the output goes into an Emacs buffer named
        !          11965: @samp{*Shell Command Output*}, which is displayed in another window but not
        !          11966: selected.  A numeric argument, as in @kbd{M-1 M-!}, directs this command to
        !          11967: insert any output into the current buffer.  In that case, point is left
        !          11968: before the output and the mark is set after the output.
        !          11969: 
        !          11970: @kindex M-|
        !          11971: @findex shell-command-on-region
        !          11972:   @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but passes
        !          11973: the contents of the region as input to the shell command, instead of no
        !          11974: input.  If a numeric argument is used, meaning insert output in the current
        !          11975: buffer, then the old region is deleted first and the output replaces it as
        !          11976: the contents of the region.@refill
        !          11977: 
        !          11978: @vindex shell-file-name
        !          11979: @cindex environment
        !          11980:   Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
        !          11981: shell to use.  This variable is initialized based on your @code{SHELL}
        !          11982: environment variable when Emacs is started.  If the file name does not
        !          11983: specify a directory, the directories in the list @code{exec-path} are
        !          11984: searched; this list is initialized based on the environment variable
        !          11985: @code{PATH} when Emacs is started.  Your @file{.emacs} file can override
        !          11986: either or both of these default initializations.@refill
        !          11987: 
        !          11988:   With @kbd{M-!} and @kbd{M-|}, Emacs has to wait until the shell command
        !          11989: completes.  You can quit with @kbd{C-g}; that terminates the shell command.
        !          11990: 
        !          11991: @node Interactive Shell, Shell Mode, Single Shell, Shell
        !          11992: @subsection Interactive Inferior Shell
        !          11993: 
        !          11994: @findex shell
        !          11995:   To run a subshell interactively, putting its typescript in an Emacs
        !          11996: buffer, use @kbd{M-x shell}.  This creates (or reuses) a buffer named
        !          11997: @samp{*shell*} and runs a subshell with input coming from and output going
        !          11998: to that buffer.  That is to say, any ``terminal output'' from the subshell
        !          11999: will go into the buffer, advancing point, and any ``terminal input'' for
        !          12000: the subshell comes from text in the buffer.  To give input to the subshell,
        !          12001: go to the end of the buffer and type the input, terminated by @key{RET}.
        !          12002: 
        !          12003:   Emacs does not wait for the subshell to do anything.  You can switch
        !          12004: windows or buffers and edit them while the shell is waiting, or while it is
        !          12005: running a command.  Output from the subshell waits until Emacs has time to
        !          12006: process it; this happens whenever Emacs is waiting for keyboard input or
        !          12007: for time to elapse.
        !          12008: 
        !          12009:   If you would like multiple subshells, change the name of buffer
        !          12010: @samp{*shell*} to something different by using @kbd{M-x rename-buffer}.  The
        !          12011: next use of @kbd{M-x shell} will create a new buffer @samp{*shell*} with
        !          12012: its own subshell.  By renaming this buffer as well you can create a third
        !          12013: one, and so on.  All the subshells run independently and in parallel.
        !          12014: 
        !          12015: @vindex explicit-shell-file-name
        !          12016:   The file name used to load the subshell is the value of the variable
        !          12017: @code{explicit-shell-file-name}, if that is non-@code{nil}.  Otherwise, the
        !          12018: environment variable @code{ESHELL} is used, or the environment variable
        !          12019: @code{SHELL} if there is no @code{ESHELL}.  If the file name specified
        !          12020: is relative, the directories in the list @code{exec-path} are searched
        !          12021: (@pxref{Single Shell,Single Shell Commands}).@refill
        !          12022: 
        !          12023:   As soon as the subshell is started, it is sent as input the contents of
        !          12024: the file @file{~/.emacs_@var{shellname}}, if that file exists, where
        !          12025: @var{shellname} is the name of the file that the shell was loaded
        !          12026: from.  For example, if you use @code{csh}, the file sent to it is
        !          12027: @file{~/.emacs_csh}; if you use the Bourne-Again shell, the file sent
        !          12028: to it is @file{~/.emacs_bash}.@refill
        !          12029: 
        !          12030: @vindex shell-pushd-regexp
        !          12031: @vindex shell-popd-regexp
        !          12032: @vindex shell-cd-regexp
        !          12033:   @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
        !          12034: shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
        !          12035: default directory the same as the shell's working directory.  These
        !          12036: commands are recognized syntactically by examining lines of input that are
        !          12037: sent.  If you use aliases for these commands, you can tell Emacs to
        !          12038: recognize them also.  For example, if the value of the variable
        !          12039: @code{shell-pushd-regexp} matches the beginning of a shell command line,
        !          12040: that line is regarded as a @code{pushd} command.  Change this variable when
        !          12041: you add aliases for @samp{pushd}.  Likewise, @code{shell-popd-regexp} and
        !          12042: @code{shell-cd-regexp} are used to recognize commands with the meaning of
        !          12043: @samp{popd} and @samp{cd}.  These commands are recognized only at the
        !          12044: beginning of a shell command line.@refill
        !          12045: 
        !          12046: @vindex shell-set-directory-error-hook
        !          12047:   If Emacs gets an error while trying to handle what it believes is
        !          12048: a @samp{cd}, @samp{pushd} or @samp{popd} command, and the value of
        !          12049: @code{shell-set-directory-error-hook} is non-@code{nil}, that value is
        !          12050: called as a function with no arguments.@refill
        !          12051: 
        !          12052: @node Shell Mode,, Interactive Shell, Shell
        !          12053: @subsection Shell Mode
        !          12054: 
        !          12055: @cindex Shell mode
        !          12056:   The shell buffer uses Shell mode, which defines several special keys
        !          12057: attached to the @kbd{C-c} prefix.  They are chosen to resemble the usual
        !          12058: editing and job control characters present in shells that are not under
        !          12059: Emacs, except that you must type @kbd{C-c} first.  Here is a complete list
        !          12060: of the special key bindings of Shell mode:
        !          12061: 
        !          12062: @kindex RET (Shell mode)
        !          12063: @kindex C-c C-d (Shell mode)
        !          12064: @kindex C-c C-u (Shell mode)
        !          12065: @kindex C-c C-w (Shell mode)
        !          12066: @kindex C-c C-c (Shell mode)
        !          12067: @kindex C-c C-z (Shell mode)
        !          12068: @kindex C-c C-\ (Shell mode)
        !          12069: @kindex C-c C-o (Shell mode)
        !          12070: @kindex C-c C-r (Shell mode)
        !          12071: @kindex C-c C-y (Shell mode)
        !          12072: @findex send-shell-input
        !          12073: @findex shell-send-eof
        !          12074: @findex interrupt-shell-subjob
        !          12075: @findex stop-shell-subjob
        !          12076: @findex quit-shell-subjob
        !          12077: @findex kill-output-from-shell
        !          12078: @findex show-output-from-shell
        !          12079: @findex copy-last-shell-input
        !          12080: @vindex shell-prompt-pattern
        !          12081: @table @kbd
        !          12082: @item @key{RET}
        !          12083: At end of buffer, send line as input; otherwise, copy current line to end of
        !          12084: buffer and send it (@code{send-shell-input}).  When a line is copied, any
        !          12085: text at the beginning of the line that matches the variable
        !          12086: @code{shell-prompt-pattern} is left out; this variable's value should be a
        !          12087: regexp string that matches the prompts that you use in your subshell.
        !          12088: @item C-c C-d
        !          12089: Send end-of-file as input, probably causing the shell or its current
        !          12090: subjob to finish (@code{shell-send-eof}).
        !          12091: @item C-c C-u
        !          12092: Kill all text that has yet to be sent as input (@code{kill-shell-input}).
        !          12093: @item C-c C-w
        !          12094: Kill a word before point (@code{backward-kill-word}).
        !          12095: @item C-c C-c
        !          12096: Interrupt the shell or its current subjob if any
        !          12097: (@code{interrupt-shell-subjob}).
        !          12098: @item C-c C-z
        !          12099: Stop the shell or its current subjob if any (@code{stop-shell-subjob}).
        !          12100: @item C-c C-\
        !          12101: Send quit signal to the shell or its current subjob if any
        !          12102: (@code{quit-shell-subjob}).
        !          12103: @item C-c C-o
        !          12104: Delete last batch of output from shell (@code{kill-output-from-shell}).
        !          12105: @item C-c C-r
        !          12106: Scroll top of last batch of output to top of window
        !          12107: (@code{show-output-from-shell}).
        !          12108: @item C-c C-y
        !          12109: Copy the previous bunch of shell input, and insert it into the
        !          12110: buffer before point (@code{copy-last-shell-input}).  No final newline
        !          12111: is inserted, and the input copied is not resubmitted until you type
        !          12112: @key{RET}.
        !          12113: @end table
        !          12114: 
        !          12115: @node Hardcopy, Dissociated Press, Shell, Top
        !          12116: @section Hardcopy Output
        !          12117: @cindex hardcopy
        !          12118: 
        !          12119:   The Emacs commands for making hardcopy derive their names from the
        !          12120: Unix commands @samp{print} and @samp{lpr}.
        !          12121: 
        !          12122: @table @kbd
        !          12123: @item M-x print-buffer
        !          12124: Print hardcopy of current buffer using Unix command @samp{print}
        !          12125: (@samp{lpr -p}).  This makes page headings containing the file name
        !          12126: and page number.
        !          12127: @item M-x lpr-buffer
        !          12128: Print hardcopy of current buffer using Unix command @samp{lpr}.
        !          12129: This makes no page headings.
        !          12130: @item M-x print-region
        !          12131: Like @code{print-buffer} but prints only the current region.
        !          12132: @item M-x lpr-region
        !          12133: Like @code{lpr-buffer} but prints only the current region.
        !          12134: @end table
        !          12135: 
        !          12136: @findex print-buffer
        !          12137: @findex print-region
        !          12138: @findex lpr-buffer
        !          12139: @findex lpr-region
        !          12140: @vindex lpr-switches
        !          12141: @vindex lpr-command
        !          12142:   All the hardcopy commands pass extra switches to the @code{lpr}
        !          12143: program based on the value of the variable @code{lpr-switches}.  Its
        !          12144: value should be a list of strings, each string a switch starting with
        !          12145: @samp{-}.  For example, the value could be @w{@code{("-Pfoo")}} to print on
        !          12146: printer @samp{foo}.  You can specify an alternative command to run
        !          12147: instead of @code{lpr} by setting the variable @code{lpr-command}.
        !          12148: 
        !          12149: @node Dissociated Press, Amusements, Hardcopy, Top
        !          12150: @section Dissociated Press
        !          12151: 
        !          12152: @findex dissociated-press
        !          12153:   @kbd{M-x dissociated-press} is a command for scrambling a file of text
        !          12154: either word by word or character by character.  Starting from a buffer of
        !          12155: straight English, it produces extremely amusing output.  The input comes
        !          12156: from the current Emacs buffer.  Dissociated Press writes its output in a
        !          12157: buffer named @samp{*Dissociation*}, and redisplays that buffer after every
        !          12158: couple of lines (approximately) to facilitate reading it.
        !          12159: 
        !          12160:   @code{dissociated-press} asks every so often whether to continue
        !          12161: operating.  Answer @kbd{n} to stop it.  You can also stop at any time by
        !          12162: typing @kbd{C-g}.  The dissociation output remains in the @samp{*Dissociation*}
        !          12163: buffer for you to copy elsewhere if you wish.
        !          12164: 
        !          12165: @cindex presidentagon
        !          12166:   Dissociated Press operates by jumping at random from one point in the
        !          12167: buffer to another.  In order to produce plausible output rather than
        !          12168: gibberish, it insists on a certain amount of overlap between the end of one
        !          12169: run of consecutive words or characters and the start of the next.  That is,
        !          12170: if it has just printed out `president' and then decides to jump to a
        !          12171: different point in the file, it might spot the `ent' in `pentagon' and
        !          12172: continue from there, producing `presidentagon'.  Long sample texts produce
        !          12173: the best results.
        !          12174: 
        !          12175: @cindex againformation
        !          12176:   A positive argument to @kbd{M-x dissociated-press} tells it to operate
        !          12177: character by character, and specifies the number of overlap characters.  A
        !          12178: negative argument tells it to operate word by word and specifies the number
        !          12179: of overlap words.  In this mode, whole words are treated as the elements to
        !          12180: be permuted, rather than characters.  No argument is equivalent to an
        !          12181: argument of two.  For your againformation, the output goes only into the
        !          12182: buffer @samp{*Dissociation*}.  The buffer you start with is not changed.
        !          12183: 
        !          12184: @cindex Markov chain
        !          12185: @cindex ignoriginal
        !          12186: @cindex techniquitous
        !          12187:   Dissociated Press produces nearly the same results as a Markov chain
        !          12188: based on a frequency table constructed from the sample text.  It is,
        !          12189: however, an independent, ignoriginal invention.  Dissociated Press
        !          12190: techniquitously copies several consecutive characters from the sample
        !          12191: between random choices, whereas a Markov chain would choose randomly for
        !          12192: each word or character.  This makes for more plausible sounding results,
        !          12193: and runs faster.
        !          12194: 
        !          12195: @cindex outragedy
        !          12196: @cindex buggestion
        !          12197: @cindex properbose
        !          12198:   It is a mustatement that too much use of Dissociated Press can be a
        !          12199: developediment to your real work.  Sometimes to the point of outragedy.
        !          12200: And keep dissociwords out of your documentation, if you want it to be well
        !          12201: userenced and properbose.  Have fun.  Your buggestions are welcome.
        !          12202: 
        !          12203: @node Amusements, Emulation, Dissociated Press, Top
        !          12204: @section Other Amusements
        !          12205: @cindex boredom
        !          12206: @findex hanoi
        !          12207: @findex yow
        !          12208: 
        !          12209:   If you are a little bit bored, you can try @kbd{M-x hanoi}.  If you are
        !          12210: considerably bored, give it a numeric argument.  If you are very very
        !          12211: bored, try an argument of 9.  Sit back and watch.
        !          12212: 
        !          12213:   When you are frustrated, try the famous Eliza program.  Just do
        !          12214: @kbd{M-x doctor}.  End each input by typing @kbd{RET} twice.
        !          12215: 
        !          12216:   When you are feeling strange, type @kbd{M-x yow}.
        !          12217: 
        !          12218: @node Emulation, Customization, Amusements, Top
        !          12219: @section Emulation
        !          12220: @cindex other editors
        !          12221: @cindex EDT
        !          12222: @cindex vi
        !          12223: 
        !          12224:   GNU Emacs can be programmed to emulate (more or less) most other
        !          12225: editors.  Standard facilities can emulate these:
        !          12226: 
        !          12227: @table @asis
        !          12228: @item EDT (DEC VMS editor)
        !          12229: @findex edt-emulation-on
        !          12230: @findex edt-emulation-off
        !          12231: Turn on EDT emulation with @kbd{M-x edt-emulation-on}.  @kbd{M-x
        !          12232: edt-emulation-off} restores normal Emacs command bindings.
        !          12233: 
        !          12234: Most of the EDT emulation commands are keypad keys, and most standard
        !          12235: Emacs key bindings are still available.  The EDT emulation rebindings
        !          12236: are done in the global keymap, so there is no problem switching
        !          12237: buffers or major modes while in EDT emulation.
        !          12238: 
        !          12239: @item Gosling Emacs
        !          12240: @findex set-gosmacs-bindings
        !          12241: @findex set-gnu-bindings
        !          12242: Turn on emulation of Gosling Emacs (aka Unipress Emacs) with @kbd{M-x
        !          12243: set-gosmacs-bindings}.  This redefines many keys, mostly on the
        !          12244: @kbd{C-x} and @kbd{ESC} prefixes, to work as they do in Gosmacs.
        !          12245: @kbd{M-x set-gnu-bindings} returns to normal GNU Emacs by rebinding
        !          12246: the same keys to the definitions they had at the time @kbd{M-x
        !          12247: set-gosmacs-bindings} was done.
        !          12248: 
        !          12249: It is also possible to run Mocklisp code written for Gosling Emacs.
        !          12250: @xref{Mocklisp}.
        !          12251: 
        !          12252: @item vi (Berkeley Unix editor)
        !          12253: @findex vi-mode
        !          12254: @cindex VI mode
        !          12255: Turn on vi emulation with @kbd{M-x vi-mode}.  This is a major mode
        !          12256: that replaces the previously established major mode.  All of the
        !          12257: vi commands that, in real vi, enter ``input'' mode are programmed
        !          12258: in the Emacs emulator to return to the previous major mode.  Thus,
        !          12259: ordinary Emacs serves as vi's ``input'' mode.
        !          12260: 
        !          12261: Because vi emulation works through major modes, it does not work
        !          12262: to switch buffers during emulation.  Return to normal Emacs first.
        !          12263: 
        !          12264: If you plan to use vi emulation much, you probably want to bind a key
        !          12265: to the @code{vi-mode} command.
        !          12266: 
        !          12267: @item vi (alternate emulator)
        !          12268: @findex vip-mode
        !          12269: Another vi emulator said to resemble real vi more thoroughly is
        !          12270: invoked by @kbd{M-x vip-mode}.  ``Input'' mode in this emulator is
        !          12271: changed from ordinary Emacs so you can use @key{ESC} to go back to
        !          12272: emulated vi command mode.  To get from emulated vi command mode back
        !          12273: to ordinary Emacs, type @kbd{C-z}.
        !          12274: 
        !          12275: This emulation does not work through major modes, and it is possible
        !          12276: to switch buffers in various ways within the emulator.  It is not
        !          12277: so necessary to assign a key to the command @code{vip-mode} as
        !          12278: it is with @code{vi-mode} because terminating insert mode does
        !          12279: not use it.
        !          12280: 
        !          12281: For full information, see the long comment at the beginning of the
        !          12282: source file, which is @file{lisp/vip.el} in the Emacs distribution.
        !          12283: @end table
        !          12284: 
        !          12285: I am interested in hearing which vi emulator users prefer, as well as in
        !          12286: receiving more complete user documentation for either or both emulators.
        !          12287: Warning: loading both at once may cause name conficts; no one has checked.
        !          12288: 
        !          12289: @node Customization, Quitting, Emulation, Top
        !          12290: @chapter Customization
        !          12291: @cindex customization
        !          12292: 
        !          12293:   This chapter talks about various topics relevant to adapting the
        !          12294: behavior of Emacs in minor ways.
        !          12295: 
        !          12296:   All kinds of customization affect only the particular Emacs job that you
        !          12297: do them in.  They are completely lost when you kill the Emacs job, and have
        !          12298: no effect on other Emacs jobs you may run at the same time or later.  The
        !          12299: only way an Emacs job can affect anything outside of it is by writing a
        !          12300: file; in particular, the only way to make a customization `permanent' is to
        !          12301: put something in your @file{.emacs} file or other appropriate file to do the
        !          12302: customization in each session.  @xref{Init File}.
        !          12303: 
        !          12304: @menu
        !          12305: * Minor Modes::     Each minor mode is one feature you can turn on
        !          12306:                      independently of any others.
        !          12307: * Variables::       Many Emacs commands examine Emacs variables
        !          12308:                      to decide what to do; by setting variables,
        !          12309:                      you can control their functioning.
        !          12310: * Keyboard Macros:: A keyboard macro records a sequence of keystrokes
        !          12311:                      to be replayed with a single command.
        !          12312: * Key Bindings::    The keymaps say what command each key runs.
        !          12313:                      By changing them, you can "redefine keys".
        !          12314: * Syntax::          The syntax table controls how words and expressions
        !          12315:                      are parsed.
        !          12316: * Init File::       How to write common customizations in the @file{.emacs} file.
        !          12317: @end menu
        !          12318: 
        !          12319: @node Minor Modes, Variables, Customization, Customization
        !          12320: @section Minor Modes
        !          12321: @cindex minor modes
        !          12322: 
        !          12323: @cindex mode line
        !          12324:   Minor modes are options which you can use or not.  For example, Auto Fill
        !          12325: mode is a minor mode in which @key{SPC} breaks lines between words as you
        !          12326: type.  All the minor modes are independent of each other and of the
        !          12327: selected major mode.  Most minor modes say in the mode line when they are
        !          12328: on; for example, @samp{Fill} in the mode line means that Auto Fill mode is
        !          12329: on.
        !          12330: 
        !          12331:   Append @code{-mode} to the name of a minor mode to get the name of a
        !          12332: command function that turns the mode on or off.  Thus, the command to
        !          12333: enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}.  These
        !          12334: commands are usually invoked with @kbd{M-x}, but you can bind keys to them
        !          12335: if you wish.  With no argument, the function turns the mode on if it was
        !          12336: off and off if it was on.  This is known as @dfn{toggling}.  A positive
        !          12337: argument always turns the mode on, and an explicit zero argument or a
        !          12338: negative argument always turns it off.
        !          12339: 
        !          12340:   Auto Fill mode allows you to enter filled text without breaking lines
        !          12341: explicitly.  Emacs inserts newlines as necessary to prevent lines from
        !          12342: becoming too long.  @xref{Filling}.
        !          12343: 
        !          12344: @cindex Overwrite mode
        !          12345: @findex overwrite-mode
        !          12346:   Overwrite mode causes ordinary printing characters to replace existing
        !          12347: text instead of shoving it over.  For example, if the point is in front of
        !          12348: the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a @kbd{G}
        !          12349: changes it to @samp{FOOGAR}, instead of making it @samp{FOOGBAR} as
        !          12350: usual.@refill
        !          12351: 
        !          12352:   Abbrev mode allows you to define abbreviations that automatically expand
        !          12353: as you type them.  For example, @samp{amd} might expand to @samp{abbrev
        !          12354: mode}.  @xref{Abbrevs}, for full information.
        !          12355: 
        !          12356: @node Variables, Keyboard Macros, Minor Modes, Customization
        !          12357: @section Variables
        !          12358: @cindex variables
        !          12359: @cindex option
        !          12360: 
        !          12361:   A @dfn{variable} is a Lisp symbol which has a value.  The symbol's name
        !          12362: is also called the name of the variable.  Variable names can contain any
        !          12363: characters, but conventionally they are chosen to be words separated by
        !          12364: hyphens.  A variable can have a documentation string which describes what
        !          12365: kind of value it should have and how the value will be used.
        !          12366: 
        !          12367:   Lisp allows any variable to have any kind of value, but most variables
        !          12368: that Emacs uses require a value of a certain type.  Often the value should
        !          12369: always be a string, or should always be a number.  Sometimes we say that a
        !          12370: certain feature is turned on if a variable is ``non-@code{nil},'' meaning
        !          12371: that if the variable's value is @code{nil}, the feature is off, but the
        !          12372: feature is on for @i{any} other value.  The conventional value to use to
        !          12373: turn on the feature---since you have to pick one particular value when you
        !          12374: set the variable---is @code{t}.
        !          12375: 
        !          12376:   Emacs uses many Lisp variables for internal recordkeeping, as any Lisp
        !          12377: program must, but the most interesting variables for you are the ones that
        !          12378: exist for the sake of customization.  Emacs does not (usually) change the
        !          12379: values of these variables; instead, you set the values, and thereby alter
        !          12380: and control the behavior of certain Emacs commands.  These variables are
        !          12381: called @dfn{options}.  Most options are documented in this manual, and
        !          12382: appear in the Variable Index (@pxref{Variable Index}).
        !          12383: 
        !          12384: @cindex right margin position
        !          12385: @cindex margin position
        !          12386:   One example of a variable which is an option is @code{fill-column}, which
        !          12387: specifies the position of the right margin (as a number of characters from
        !          12388: the left margin) to be used by the fill commands (@pxref{Filling}).
        !          12389: 
        !          12390: @menu
        !          12391: * Examining::           Examining or setting one variable's value.
        !          12392: * Edit Options::        Examining or editing list of all variables' values.
        !          12393: * Locals::              Per-buffer values of variables.
        !          12394: * File Variables::      How files can specify variable values.
        !          12395: @end menu
        !          12396: 
        !          12397: @node Examining, Edit Options, Variables, Variables
        !          12398: @subsection Examining and Setting Variables
        !          12399: @cindex setting variables
        !          12400: 
        !          12401: @table @kbd
        !          12402: @item C-h v
        !          12403: @itemx M-x describe-variable
        !          12404: Print the value and documentation of a variable.
        !          12405: @item M-x set-variable
        !          12406: Change the value of a variable.
        !          12407: @end table
        !          12408: 
        !          12409: @kindex C-h v
        !          12410: @findex describe-variable
        !          12411: @c !!! following written verbosely to avoid overfull hbox
        !          12412:   To examine the value of a single variable, type @kbd{C-h v}
        !          12413: (@code{describe-variable}), which reads a variable name using the
        !          12414: minibuffer, with completion.  It prints both the value and the
        !          12415: documentation of the variable.
        !          12416: 
        !          12417: @example
        !          12418: C-h v fill-column @key{RET}
        !          12419: @end example
        !          12420: @noindent
        !          12421: prints something like
        !          12422: @smallexample
        !          12423: @group
        !          12424: fill-column's value is 72
        !          12425: 
        !          12426: Documentation:
        !          12427: *Column beyond which automatic line-wrapping should happen.
        !          12428: Automatically becomes local when set in any fashion.
        !          12429: @end group
        !          12430: @end smallexample
        !          12431: 
        !          12432: @cindex option
        !          12433: @noindent
        !          12434: The star at the beginning of the documentation indicates that this variable
        !          12435: is an option.  @kbd{C-h v} is not restricted to options; it allows any
        !          12436: variable name.
        !          12437: 
        !          12438: @findex set-variable
        !          12439:   If you know which option you want to set, you can set it using @kbd{M-x
        !          12440: set-variable}.  This reads the variable name with the minibuffer (with
        !          12441: completion), and then reads a Lisp expression for the new value using the
        !          12442: minibuffer a second time.  For example,
        !          12443: 
        !          12444: @example
        !          12445: M-x set-variable @key{RET} fill-column @key{RET} 72 @key{RET}
        !          12446: @end example
        !          12447: 
        !          12448: @noindent
        !          12449: sets @code{fill-column} to 72, like executing the Lisp expression
        !          12450: 
        !          12451: @example
        !          12452: (setq fill-column 72)
        !          12453: @end example
        !          12454: 
        !          12455:   Setting variables in this way, like all means of customizing Emacs
        !          12456: except where explicitly stated, affects only the current Emacs session.
        !          12457: 
        !          12458: @node Edit Options, Locals, Examining, Variables
        !          12459: @subsection Editing Variable Values
        !          12460: 
        !          12461: @table @kbd
        !          12462: @item M-x list-options
        !          12463: Display a buffer listing names, values and documentation of all options.
        !          12464: @item M-x edit-options
        !          12465: Change option values by editing a list of options.
        !          12466: @end table
        !          12467: 
        !          12468: @findex list-options
        !          12469:   @kbd{M-x list-options} displays a list of all Emacs option variables, in
        !          12470: an Emacs buffer named @samp{*List Options*}.  Each option is shown with its
        !          12471: documentation and its current value.  Here is what a portion of it might
        !          12472: look like:
        !          12473: 
        !          12474: @smallexample
        !          12475: @group
        !          12476: ;; exec-path:
        !          12477: ("." "/usr/local/bin" "/usr/ucb" "/bin" "/usr/bin" "/u2/emacs/etc")
        !          12478: *List of directories to search programs to run in subprocesses.
        !          12479: Each element is a string (directory name)
        !          12480: or nil (try the default directory).
        !          12481: ;;
        !          12482: ;; fill-column:
        !          12483: 72
        !          12484: *Column beyond which automatic line-wrapping should happen.
        !          12485: Automatically becomes local when set in any fashion.
        !          12486: ;;
        !          12487: @end group
        !          12488: @end smallexample
        !          12489: 
        !          12490: @findex edit-options
        !          12491: @cindex Options mode
        !          12492:   @kbd{M-x edit-options} goes one step further and immediately selects the
        !          12493: @samp{*List Options*} buffer; this buffer uses the major mode Options mode,
        !          12494: which provides commands that allow you to point at an option and change its
        !          12495: value:
        !          12496: 
        !          12497: @table @kbd
        !          12498: @item s
        !          12499: Set the variable point is in or near to a new value read using the
        !          12500: minibuffer.
        !          12501: @item x
        !          12502: Toggle the variable point is in or near: if the value was @code{nil},
        !          12503: it becomes @code{t}; otherwise it becomes @code{nil}.
        !          12504: @item 1
        !          12505: Set the variable point is in or near to @code{t}.
        !          12506: @item 0
        !          12507: Set the variable point is in or near to @code{nil}.
        !          12508: @item n
        !          12509: @itemx p
        !          12510: Move to the next or previous variable.
        !          12511: @end table
        !          12512: 
        !          12513:   Changes take effect immediately.
        !          12514: 
        !          12515: @node Locals, File Variables, Edit Options, Variables
        !          12516: @subsection Local Variables
        !          12517: 
        !          12518: @table @kbd
        !          12519: @item M-x make-local-variable
        !          12520: Make a variable have a local value in the current buffer.
        !          12521: @item M-x kill-local-variable
        !          12522: Make a variable use its global value in the current buffer.
        !          12523: @item M-x make-variable-buffer-local
        !          12524: Mark a variable so that setting it will make it local to the
        !          12525: buffer that is current at that time.
        !          12526: @end table
        !          12527: 
        !          12528: @cindex local variables
        !          12529:   Any variable can be made @dfn{local} to a specific Emacs buffer.  This
        !          12530: means that its value in that buffer is independent of its value in other
        !          12531: buffers.  A few variables are always local in every buffer.  Every other
        !          12532: Emacs variable has a @dfn{global} value which is in effect in all buffers
        !          12533: that have not made the variable local.
        !          12534: 
        !          12535:   Major modes always make the variables they set local to the buffer.
        !          12536: This is why changing major modes in one buffer has no effect on other
        !          12537: buffers.
        !          12538: 
        !          12539: @findex make-local-variable
        !          12540:   @kbd{M-x make-local-variable} reads the name of a variable and makes it
        !          12541: local to the current buffer.  Further changes in this buffer will not
        !          12542: affect others, and further changes in the global value will not affect this
        !          12543: buffer.
        !          12544: 
        !          12545: @findex make-variable-buffer-local
        !          12546: @cindex per-buffer variables
        !          12547:   @kbd{M-x make-variable-buffer-local} reads the name of a variable and
        !          12548: changes the future behavior of the variable so that it will become local
        !          12549: automatically when it is set.  More precisely, once a variable has been
        !          12550: marked in this way, the usual ways of setting the variable will
        !          12551: automatically do @code{make-local-variable} first.  We call such variables
        !          12552: @dfn{per-buffer} variables.
        !          12553: 
        !          12554: @c !!! following paragraph rewritten to avoid overfull hbox
        !          12555:   Some important variables have been marked per-buffer already.  These include
        !          12556: @code{abbrev-mode}, @code{auto-fill-hook}, @code{case-fold-search},
        !          12557: @code{ctl-arrow}, @code{comment-column}, @code{fill-column},
        !          12558: @code{fill-prefix}, @code{indent-tabs-mode}, @code{left-margin},
        !          12559: @code{mode-line-format}, @code{overwrite-mode},
        !          12560: @code{selective-display}, 
        !          12561: @code{tab-width}, 
        !          12562: @code{selective-display-ellipses},
        !          12563: and @code{truncate-lines}.  Some other variables are
        !          12564: always local in every buffer, but they are used for internal
        !          12565: purposes.@refill
        !          12566: 
        !          12567: @findex kill-local-variable
        !          12568:   @kbd{M-x kill-local-variable} reads the name of a variable and makes it
        !          12569: cease to be local to the current buffer.  The global value of the variable
        !          12570: henceforth is in effect in this buffer.  Setting the major mode kills all
        !          12571: the local variables of the buffer.
        !          12572: 
        !          12573: @findex setq-default
        !          12574:   To set the global value of a variable, regardless of whether the
        !          12575: variable has a local value in the current buffer, you can use the
        !          12576: Lisp function @w{@code{setq-default}}.  It works like @code{setq}.
        !          12577: If there is a local value in the current buffer, the local value is
        !          12578: not affected by @code{setq-default}; thus, the new global value may
        !          12579: not be visible until you switch to another buffer.  For example,
        !          12580: 
        !          12581: @example
        !          12582: (setq-default fill-column 72)
        !          12583: @end example
        !          12584: 
        !          12585: @noindent
        !          12586: @code{setq-default} is the only way to set the global value of a variable
        !          12587: that has been marked with @code{make-variable-buffer-local}.
        !          12588: 
        !          12589: @findex default-value
        !          12590:   Programs can look at a variable's default value with @code{default-value}.
        !          12591: This function takes a symbol as argument and returns its default value.
        !          12592: The argument is evaluated; usually you must quote it explicitly.  For
        !          12593: example,
        !          12594: 
        !          12595: @example
        !          12596: (default-value 'fill-column)
        !          12597: @end example
        !          12598: 
        !          12599: @node File Variables,, Locals, Variables
        !          12600: @subsection Local Variables in Files
        !          12601: @cindex local variables in files
        !          12602: 
        !          12603:   A file can contain a @dfn{local variables list}, which specifies the
        !          12604: values to use for certain Emacs variables when that file is edited.
        !          12605: Visiting the file checks for a local variables list and makes each variable
        !          12606: in the list local to the buffer in which the file is visited, with the
        !          12607: value specified in the file.
        !          12608: 
        !          12609:   A local variables list goes near the end of the file, in the last page.
        !          12610: (It is often best to put it on a page by itself.)  The local variables list
        !          12611: starts with a line containing the string @samp{Local Variables:}, and ends
        !          12612: with a line containing the string @samp{End:}.  In between come the
        !          12613: variable names and values, one set per line, as @samp{@var{variable}:@:
        !          12614: @var{value}}.  The @var{value}s are not evaluated; they are used literally.
        !          12615: 
        !          12616:   The line which starts the local variables list does not have to say just
        !          12617: @samp{Local Variables:}.  If there is other text before @samp{Local
        !          12618: Variables:}, that text is called the @dfn{prefix}, and if there is other
        !          12619: text after, that is called the @dfn{suffix}.  If these are present, each
        !          12620: entry in the local variables list should have the prefix before it and the
        !          12621: suffix after it.  This includes the @samp{End:} line.  The prefix and
        !          12622: suffix are included to disguise the local variables list as a comment so
        !          12623: that the compiler or text formatter will not be perplexed by it.  If you do
        !          12624: not need to disguise the local variables list as a comment in this way, do
        !          12625: not bother with a prefix or a suffix.@refill
        !          12626: 
        !          12627:   Two ``variable'' names are special in a local variables list: a value for
        !          12628: the variable @code{mode} really sets the major mode, and a value for the
        !          12629: variable @code{eval} is simply evaluated as an expression and the value is
        !          12630: ignored.  These are not real variables; setting such variables in any other
        !          12631: context has no such effect.  If @code{mode} is used in a local variables
        !          12632: list, it should be the first entry in the list.
        !          12633: 
        !          12634:   Here is an example of a local variables list:
        !          12635: 
        !          12636: @example
        !          12637: ;;; Local Variables: ***
        !          12638: ;;; mode:lisp ***
        !          12639: ;;; comment-column:0 ***
        !          12640: ;;; comment-start: ";;; "  ***
        !          12641: ;;; comment-end:"***" ***
        !          12642: ;;; End: ***
        !          12643: @end example
        !          12644: 
        !          12645:   Note that the prefix is @samp{;;; } and the suffix is @samp{ ***}.  Note also
        !          12646: that comments in the file begin with and end with the same strings.
        !          12647: Presumably the file contains code in a language which is like Lisp
        !          12648: (like it enough for Lisp mode to be useful) but in which comments start
        !          12649: and end in that way.  The prefix and suffix are used in the local
        !          12650: variables list to make the list appear as comments when the file is read
        !          12651: by the compiler or interpreter for that        language.
        !          12652: 
        !          12653:   The start of the local variables list must be no more than 3000
        !          12654: characters from the end of the file, and must be in the last page if the
        !          12655: file is divided into pages.  Otherwise, Emacs will not notice it is there.
        !          12656: The purpose of this is so that a stray @samp{Local Variables:}@: not in the
        !          12657: last page does not confuse Emacs, and so that visiting a long file that is
        !          12658: all one page and has no local variables list need not take the time to
        !          12659: search the whole file.
        !          12660: 
        !          12661: @cindex local variables and Auto Fill
        !          12662:   You may be tempted to try to turn on Auto Fill mode with a local variable
        !          12663: list.  That is a mistake.  The choice of Auto Fill mode or not is a matter
        !          12664: of individual taste, not a matter of the contents of particular files.
        !          12665: If you want to use Auto Fill, set up major mode hooks with your @file{.emacs}
        !          12666: file to turn it on (when appropriate) for you alone (@pxref{Init File}).
        !          12667: Don't try to use a local variable list that would impose your taste on
        !          12668: everyone.
        !          12669: 
        !          12670: @vindex inhibit-local-variables
        !          12671:   If you are concerned that you might visit a file containing a Trojan-horse
        !          12672: local variable specification, you can prevent local variables processing
        !          12673: by setting the variable @code{inhibit-local-variables} to a non-@code{nil}
        !          12674: value.  Emacs will display the local variables specification and then ask
        !          12675: you whether to process it.
        !          12676: 
        !          12677: @node Keyboard Macros, Key Bindings, Variables, Customization
        !          12678: @section Keyboard Macros
        !          12679: 
        !          12680: @cindex keyboard macros
        !          12681:   A @dfn{keyboard macro} is a command defined by the user to abbreviate a
        !          12682: sequence of keys.  For example, if you discover that you are about to type
        !          12683: @kbd{C-n C-d} forty times, you can speed your work by defining a keyboard
        !          12684: macro to do @kbd{C-n C-d} and calling it with a repeat count of forty.
        !          12685: 
        !          12686: @c widecommands
        !          12687: @table @kbd
        !          12688: @item C-x (
        !          12689: Start defining a keyboard macro (@code{start-kbd-macro}).
        !          12690: @item C-x )
        !          12691: End the definition of a keyboard macro (@code{end-kbd-macro}).
        !          12692: @item C-x e
        !          12693: Execute the most recent keyboard macro (@code{call-last-kbd-macro}).
        !          12694: @item C-u C-x (
        !          12695: Re-execute last keyboard macro, then add more keys to its @w{definition}.
        !          12696: @item C-x q
        !          12697: When this point is reached during macro execution, ask for confirmation
        !          12698: (@code{kbd-macro-query}).
        !          12699: @item M-x name-last-kbd-macro
        !          12700: Give a command name (for the duration of the session) to the most
        !          12701: recently defined keyboard macro.
        !          12702: @item M-x insert-kbd-macro
        !          12703: Insert in the buffer a keyboard macro's definition, as Lisp code.
        !          12704: @end table
        !          12705: 
        !          12706:   Keyboard macros differ from ordinary Emacs commands in that they are
        !          12707: written in the Emacs command language rather than in Lisp.  This makes it
        !          12708: easier for the novice to write them, and makes them more convenient as
        !          12709: temporary hacks.  However, the Emacs command language is not powerful
        !          12710: enough as a programming language to be useful for writing anything
        !          12711: intelligent or general.  For such things, Lisp must be used.
        !          12712: 
        !          12713:   You define a keyboard macro while executing the commands which are the
        !          12714: definition.  Put differently, as you are defining a keyboard macro, the
        !          12715: definition is being executed for the first time.  This way, you can see
        !          12716: what the effects of your commands are, so that you don't have to figure
        !          12717: them out in your head.  When you are finished, the keyboard macro is
        !          12718: defined and also has been, in effect, executed once.  You can then do the
        !          12719: whole thing over again by invoking the macro.
        !          12720: 
        !          12721: @menu
        !          12722: * Basic Kbd Macro::     Defining and running keyboard macros.
        !          12723: * Save Kbd Macro::      Giving keyboard macros names; saving them in files.
        !          12724: * Kbd Macro Query::     Keyboard macros that do different things each use.
        !          12725: @end menu
        !          12726: 
        !          12727: @node Basic Kbd Macro, Save Kbd Macro, Keyboard Macros, Keyboard Macros
        !          12728: @subsection Basic Use
        !          12729: 
        !          12730: @kindex C-x (
        !          12731: @kindex C-x )
        !          12732: @kindex C-x e
        !          12733: @findex start-kbd-macro
        !          12734: @findex end-kbd-macro
        !          12735: @findex call-last-kbd-macro
        !          12736:   To start defining a keyboard macro, type the @kbd{C-x (} command
        !          12737: (@code{start-kbd-macro}).  From then on, your keys continue to be
        !          12738: executed, but also become part of the definition of the macro.  @samp{Def}
        !          12739: appears in the mode line to remind you of what is going on.  When you are
        !          12740: finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the
        !          12741: definition (without becoming part of it!).  
        !          12742: 
        !          12743: @example
        !          12744: @group
        !          12745: @exdent For example,
        !          12746: 
        !          12747: C-x ( M-F foo C-x )
        !          12748: @end group
        !          12749: @end example
        !          12750: 
        !          12751: @noindent
        !          12752: defines a macro to move forward a word and then insert @samp{foo}.
        !          12753: 
        !          12754:   The macro thus defined can be invoked again with the @kbd{C-x e} command
        !          12755: (@code{call-last-kbd-macro}), which may be given a repeat count as a
        !          12756: numeric argument to execute the macro many times.  @kbd{C-x )} can also be
        !          12757: given a repeat count as an argument, in which case it repeats the macro
        !          12758: that many times right after defining it, but defining the macro counts as
        !          12759: the first repetition (since it is executed as you define it).  So, giving
        !          12760: @kbd{C-x )} an argument of 4 executes the macro immediately 3 additional
        !          12761: times.  An argument of zero to @kbd{C-x e} or @kbd{C-x )} means repeat the
        !          12762: macro indefinitely (until it gets an error or you type @kbd{C-g}).
        !          12763: 
        !          12764:   If you wish to repeat an operation at regularly spaced places in the
        !          12765: text, define a macro and include as part of the macro the commands to move
        !          12766: to the next place you want to use it.  For example, if you want to change
        !          12767: each line, you should position point at the start of a line, and define a
        !          12768: macro to change that line and leave point at the start of the next line.
        !          12769: Then repeating the macro will operate on successive lines.
        !          12770: 
        !          12771:   After you have terminated the definition of a keyboard macro, you can add
        !          12772: to the end of its definition by typing @kbd{C-u C-x (}.  This is equivalent
        !          12773: to plain @kbd{C-x (} followed by retyping the whole definition so far.  As
        !          12774: a consequence it re-executes the macro as previously defined.
        !          12775: 
        !          12776:   One limitation on the use of keyboard macros is that if you exit a
        !          12777: recursive edit within a macro that was not entered within the macro,
        !          12778: then the execution of the macro stops at that point.  In Emacs 18, View
        !          12779: mode uses a recursive edit, so exiting View mode is an occasion for such
        !          12780: a problem.
        !          12781: 
        !          12782: @node Save Kbd Macro, Kbd Macro Query, Basic Kbd Macro, Keyboard Macros
        !          12783: @subsection Naming and Saving Keyboard Macros
        !          12784: 
        !          12785: @findex name-last-kbd-macro
        !          12786:   If you wish to save a keyboard macro for longer than until you define the
        !          12787: next one, you must give it a name using @kbd{M-x name-last-kbd-macro}.
        !          12788: This reads a name as an argument using the minibuffer and defines that name
        !          12789: to execute the macro.  The macro name is a Lisp symbol, and defining it in
        !          12790: this way makes it a valid command name for calling with @kbd{M-x} or for
        !          12791: binding a key to with @code{global-set-key} (@pxref{Keymaps}).  If you
        !          12792: specify a name that has a prior definition other than another keyboard
        !          12793: macro, an error message is printed and nothing is changed.
        !          12794: 
        !          12795: @findex insert-kbd-macro
        !          12796:   Once a macro has a command name, you can save its definition in a file.
        !          12797: Then it can be used in another editing session.  First visit the file
        !          12798: you want to save the definition in.  Then use the command
        !          12799: 
        !          12800: @example
        !          12801: M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET}
        !          12802: @end example
        !          12803: 
        !          12804: @noindent
        !          12805: This inserts some Lisp code that, when executed later, will define the same
        !          12806: macro with the same definition it has now.  You need not understand Lisp
        !          12807: code to do this, because @code{insert-kbd-macro} writes the Lisp code for you.
        !          12808: Then save the file.  The file can be loaded with @code{load-file}
        !          12809: (@pxref{Lisp Libraries}).  If the file you save in is your init file
        !          12810: @file{~/.emacs} (@pxref{Init File}) then the macro will be defined each
        !          12811: time you run Emacs.
        !          12812: 
        !          12813:   If you give @code{insert-kbd-macro} a prefix argument, it makes
        !          12814: additional Lisp code to record the keys (if any) that you have bound to the
        !          12815: keyboard macro, so that the macro will be reassigned the same keys when you
        !          12816: load the file.
        !          12817: 
        !          12818: @node Kbd Macro Query,, Save Kbd Macro, Keyboard Macros
        !          12819: @subsection Executing Macros with Variations
        !          12820: 
        !          12821: @kindex C-x q
        !          12822: @findex kbd-macro-query
        !          12823:   Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect similar
        !          12824: to that of @code{query-replace}, where the macro asks you each time around
        !          12825: whether to make a change.  When you are defining the macro, type @kbd{C-x
        !          12826: q} at the point where you want the query to occur.  During macro
        !          12827: definition, the @kbd{C-x q} does nothing, but when the macro is invoked the
        !          12828: @kbd{C-x q} reads a character from the terminal to decide whether to
        !          12829: continue.
        !          12830: 
        !          12831:   The special answers are @key{SPC}, @key{DEL}, @kbd{C-d}, @kbd{C-l} and
        !          12832: @kbd{C-r}.  Any other character terminates execution of the keyboard macro
        !          12833: and is then read as a command.  @key{SPC} means to continue.  @key{DEL}
        !          12834: means to skip the remainder of this repetition of the macro, starting again
        !          12835: from the beginning in the next repetition.  @kbd{C-d} means to skip the
        !          12836: remainder of this repetition and cancel further repetition.  @kbd{C-l}
        !          12837: redraws the screen and asks you again for a character to say what to do.
        !          12838: @kbd{C-r} enters a recursive editing level, in which you can perform
        !          12839: editing which is not part of the macro.  When you exit the recursive edit
        !          12840: using @kbd{C-M-c}, you are asked again how to continue with the keyboard
        !          12841: macro.  If you type a @key{SPC} at this time, the rest of the macro
        !          12842: definition is executed.  It is up to you to leave point and the text in a
        !          12843: state such that the rest of the macro will do what you want.@refill
        !          12844: 
        !          12845:   @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, performs a
        !          12846: different function.  It enters a recursive edit reading input from the
        !          12847: keyboard, both when you type it during the definition of the macro, and
        !          12848: when it is executed from the macro.  During definition, the editing you do
        !          12849: inside the recursive edit does not become part of the macro.  During macro
        !          12850: execution, the recursive edit gives you a chance to do some particularized
        !          12851: editing.  @xref{Recursive Edit}.
        !          12852: 
        !          12853: @node Key Bindings, Syntax, Keyboard Macros, Customization
        !          12854: @section Customizing Key Bindings
        !          12855: 
        !          12856:   This section deals with the @dfn{keymaps} which define the bindings
        !          12857: between keys and functions, and shows how you can customize these bindings.
        !          12858: @cindex command
        !          12859: @cindex function
        !          12860: @cindex command name
        !          12861: 
        !          12862:   A command is a Lisp function whose definition provides for interactive
        !          12863: use.  Like every Lisp function, a command has a function name, a Lisp
        !          12864: symbol whose name usually consists of lower case letters and hyphens.
        !          12865: 
        !          12866: @menu
        !          12867: * Keymaps::    Definition of the keymap data structure.
        !          12868:                Names of Emacs's standard keymaps.
        !          12869: * Rebinding::  How to redefine one key's meaning conveniently.
        !          12870: * Disabling::  Disabling a command means confirmation is required
        !          12871:                 before it can be executed.  This is done to protect
        !          12872:                 beginners from surprises.
        !          12873: @end menu
        !          12874: 
        !          12875: @node Keymaps, Rebinding, Key Bindings, Key Bindings
        !          12876: @subsection Keymaps
        !          12877: @cindex keymap
        !          12878: 
        !          12879: @cindex global keymap
        !          12880: @vindex global-map
        !          12881:   The bindings between characters and command functions are recorded in
        !          12882: data structures called @dfn{keymaps}.  Emacs has many of these.  One, the
        !          12883: @dfn{global} keymap, defines the meanings of the single-character keys that
        !          12884: are defined regardless of major mode.  It is the value of the variable
        !          12885: @code{global-map}.
        !          12886: 
        !          12887: @cindex local keymap
        !          12888: @vindex c-mode-map
        !          12889: @vindex lisp-mode-map
        !          12890:   Each major mode has another keymap, its @dfn{local keymap}, which
        !          12891: contains overriding definitions for the single-character keys that are to
        !          12892: be redefined in that mode.  Each buffer records which local keymap is
        !          12893: installed for it at any time, and the current buffer's local keymap is the
        !          12894: only one that directly affects command execution.  The local keymaps for
        !          12895: Lisp mode, C mode, and many other major modes always exist even when not in
        !          12896: use.  They are the values of the variables @code{lisp-mode-map},
        !          12897: @code{c-mode-map}, and so on.  For major modes less often used, the local
        !          12898: keymap is sometimes constructed only when the mode is used for the first
        !          12899: time in a session.  This is to save space.
        !          12900: 
        !          12901: @cindex minibuffer
        !          12902: @vindex minibuffer-local-map
        !          12903: @vindex minibuffer-local-ns-map
        !          12904: @vindex minibuffer-local-completion-map
        !          12905: @vindex minibuffer-local-must-match-map
        !          12906: @vindex repeat-complex-command-map
        !          12907:   There are local keymaps for the minibuffer too; they contain various
        !          12908: completion and exit commands.
        !          12909: 
        !          12910: @itemize @bullet
        !          12911: @item
        !          12912: @code{minibuffer-local-map} is used for ordinary input (no completion).
        !          12913: @item
        !          12914: @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
        !          12915: just like @key{RET}.  This is used mainly for Mocklisp compatibility.
        !          12916: @item
        !          12917: @code{minibuffer-local-completion-map} is for permissive completion.
        !          12918: @item
        !          12919: @code{minibuffer-local-must-match-map} is for strict completion and
        !          12920: for cautious completion.
        !          12921: @item
        !          12922: @code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
        !          12923: @end itemize
        !          12924: 
        !          12925: @vindex ctl-x-map
        !          12926: @vindex help-map
        !          12927: @vindex esc-map
        !          12928:   Finally, each prefix key has a keymap which defines the key sequences
        !          12929: that start with it.  For example, @code{ctl-x-map} is the keymap used for
        !          12930: characters following a @kbd{C-x}.
        !          12931: 
        !          12932: @itemize @bullet
        !          12933: @item
        !          12934: @code{ctl-x-map} is the variable name for the map used for characters that
        !          12935: follow @kbd{C-x}.
        !          12936: @item
        !          12937: @code{help-map} is used for characters that follow @kbd{C-h}.
        !          12938: @item
        !          12939: @code{esc-map} is for characters that follow @key{ESC}.  Thus, all Meta
        !          12940: characters are actually defined by this map.
        !          12941: @item
        !          12942: @code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}.
        !          12943: @item
        !          12944: @code{mode-specific-map} is for characters that follow @kbd{C-c}.
        !          12945: @end itemize
        !          12946: 
        !          12947:   The definition of a prefix key is just the keymap to use for looking up
        !          12948: the following character.  Actually, the definition is sometimes a Lisp
        !          12949: symbol whose function definition is the following character keymap.  The
        !          12950: effect is the same, but it provides a command name for the prefix key that
        !          12951: can be used as a description of what the prefix key is for.  Thus, the
        !          12952: binding of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function
        !          12953: definition is the keymap for @kbd{C-x} commands, the value of
        !          12954: @code{ctl-x-map}.@refill
        !          12955: 
        !          12956:   Prefix key definitions of this sort can appear in either the global map
        !          12957: or a local map.  The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC}
        !          12958: as prefix keys appear in the global map, so these prefix keys are always
        !          12959: available.  Major modes can locally redefine a key as a prefix by putting
        !          12960: a prefix key definition for it in the local map.@refill
        !          12961: 
        !          12962:   A mode can also put a prefix definition of a global prefix character such
        !          12963: as @kbd{C-x} into its local map.  This is how major modes override the
        !          12964: definitions of certain keys that start with @kbd{C-x}.  This case is
        !          12965: special, because the local definition does not entirely replace the global
        !          12966: one.  When both the global and local definitions of a key are other
        !          12967: keymaps, the next character is looked up in both keymaps, with the local
        !          12968: definition overriding the global one as usual.  So, the character after the
        !          12969: @kbd{C-x} is looked up in both the major mode's own keymap for redefined
        !          12970: @kbd{C-x} commands and in @code{ctl-x-map}.  If the major mode's own keymap
        !          12971: for @kbd{C-x} commands contains @code{nil}, the definition from the global
        !          12972: keymap for @kbd{C-x} commands is used.@refill
        !          12973: 
        !          12974: @cindex sparse keymap
        !          12975:   A keymap is actually a Lisp object.  The simplest form of keymap is a
        !          12976: Lisp vector of length 128.  The binding for a character in such a keymap is
        !          12977: found by indexing into the vector with the character as an index.  A keymap
        !          12978: can also be a Lisp list whose @sc{car} is the symbol @code{keymap} and whose
        !          12979: remaining elements are pairs of the form @code{(@var{char} .@: @var{binding})}.
        !          12980: Such lists are called @dfn{sparse keymaps} because they are used when most
        !          12981: of the characters' entries will be @code{nil}.  Sparse keymaps are used
        !          12982: mainly for prefix characters.
        !          12983: 
        !          12984:   Keymaps are only of length 128, so what about Meta characters, whose
        !          12985: codes are from 128 to 255?  A key that contains a Meta character actually
        !          12986: represents it as a sequence of two characters, the first of which is
        !          12987: @key{ESC}.  So the key @kbd{M-a} is really represented as @kbd{@key{ESC}
        !          12988: a}, and its binding is found at the slot for @samp{a} in
        !          12989: @code{esc-map}.@refill
        !          12990: 
        !          12991: @node Rebinding, Disabling, Keymaps, Key Bindings
        !          12992: @subsection Changing Key Bindings Interactively
        !          12993: @cindex key rebinding, this session
        !          12994: @cindex rebinding keys, this session
        !          12995: @cindex rebinding keys, this session
        !          12996: 
        !          12997:   The way to redefine an Emacs key is to change its entry in a keymap.
        !          12998: You can change the global keymap, in which case the change is effective in
        !          12999: all major modes (except those that have their own overriding local
        !          13000: definitions for the same key).  Or you can change the current buffer's
        !          13001: local map, which affects all buffers using the same major mode.
        !          13002: @findex global-set-key
        !          13003: @findex local-set-key
        !          13004: 
        !          13005: @table @kbd
        !          13006: @item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}
        !          13007: Defines @var{key} globally to run @var{cmd}.
        !          13008: @item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}
        !          13009: Defines @var{key} locally (in the major mode now in effect) to run
        !          13010: @var{cmd}.
        !          13011: @end table
        !          13012: 
        !          13013:   For example,
        !          13014: 
        !          13015: @example
        !          13016: M-x global-set-key @key{RET} C-f next-line @key{RET}
        !          13017: @end example
        !          13018: 
        !          13019: @noindent
        !          13020: would redefine @kbd{C-f} to move down a line.  The fact that @var{cmd} is
        !          13021: read second makes it serve as a kind of confirmation for @var{key}.
        !          13022: 
        !          13023:   These functions offer no way to specify a particular prefix keymap as the
        !          13024: one to redefine in, but that is not necessary, as you can include prefixes
        !          13025: in @var{key}.  @var{key} is read by reading characters one by one until
        !          13026: they amount to a complete key (that is, not a prefix key).  Thus, if you
        !          13027: type @kbd{C-f} for @var{key}, that's the end; the minibuffer is entered
        !          13028: immediately to read @var{cmd}.  But if you type @kbd{C-x}, another
        !          13029: character is read; if that is @kbd{4}, another character is read, and so
        !          13030: on.  For example,@refill
        !          13031: 
        !          13032: @example
        !          13033: M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET}
        !          13034: @end example
        !          13035: 
        !          13036: @noindent
        !          13037: would redefine @kbd{C-x 4 $} to run the (fictitious) command
        !          13038: @code{spell-other-window}.
        !          13039: 
        !          13040:   All the key sequences which consist of @kbd{C-c} followed by a letter
        !          13041: are supposed to be reserved for user customization.  That is, Emacs Lisp
        !          13042: libraries should not define any of these commands.
        !          13043: 
        !          13044: @findex define-key
        !          13045: @findex substitute-key-definition
        !          13046:   The most general way to modify a keymap is the function @code{define-key},
        !          13047: used in Lisp code (such as your @file{.emacs} file).  @code{define-key}
        !          13048: takes three arguments: the keymap, the key to modify in it, and the new
        !          13049: definition.  @xref{Init File}, for an example.  @code{substitute-key-definition}
        !          13050: is used similarly; it takes three arguments, an old definition, a new
        !          13051: definition and a keymap, and redefines in that keymap all keys that were
        !          13052: previously defined with the old definition to have the new definition
        !          13053: instead.
        !          13054: 
        !          13055: @node Disabling,, Rebinding, Key Bindings
        !          13056: @subsection Disabling Commands
        !          13057: @cindex disabled command
        !          13058: 
        !          13059:   Disabling a command marks the command as requiring confirmation before it
        !          13060: can be executed.  The purpose of disabling a command is to prevent
        !          13061: beginning users from executing it by accident and being confused.
        !          13062: 
        !          13063:   The direct mechanism for disabling a command is to have a non-@code{nil}
        !          13064: @code{disabled} property on the Lisp symbol for the command.  These
        !          13065: properties are normally set up by the user's @file{.emacs} file with
        !          13066: Lisp expressions such as
        !          13067: 
        !          13068: @example
        !          13069: (put 'delete-region 'disabled t)
        !          13070: @end example
        !          13071: 
        !          13072:   If the value of the @code{disabled} property is a string, that string
        !          13073: is included in the message printed when the command is used:
        !          13074: 
        !          13075: @example
        !          13076: (put 'delete-region 'disabled
        !          13077:      "Text deleted this way cannot be yanked back!\n")
        !          13078: @end example
        !          13079: 
        !          13080: @findex disable-command
        !          13081: @findex enable-command
        !          13082:   You can make a command disabled either by editing the @file{.emacs} file
        !          13083: directly or with the command @kbd{M-x disable-command}, which edits the
        !          13084: @file{.emacs} file for you.  @xref{Init File}.
        !          13085: 
        !          13086:   Attempting to invoke a disabled command interactively in Emacs causes the
        !          13087: display of a window containing the command's name, its documentation, and
        !          13088: some instructions on what to do immediately; then Emacs asks for input
        !          13089: saying whether to execute the command as requested, enable it and execute,
        !          13090: or cancel it.  If you decide to enable the command, you are asked whether to
        !          13091: do this permanently or just for the current session.  Enabling permanently
        !          13092: works by automatically editing your @file{.emacs} file.  You can use
        !          13093: @kbd{M-x enable-command} at any time to enable any command permanently.
        !          13094: 
        !          13095:   Whether a command is disabled is independent of what key is used to
        !          13096: invoke it; it also applies if the command is invoked using @kbd{M-x}.
        !          13097: Disabling a command has no effect on calling it as a function from Lisp
        !          13098: programs.
        !          13099: 
        !          13100: @node Syntax, Init File, Key Bindings, Customization
        !          13101: @section The Syntax Table
        !          13102: @cindex syntax table
        !          13103: 
        !          13104:   All the Emacs commands which parse words or balance parentheses are
        !          13105: controlled by the @dfn{syntax table}.  The syntax table says which
        !          13106: characters are opening delimiters, which are parts of words, which are
        !          13107: string quotes, and so on.  Actually, each major mode has its own syntax
        !          13108: table (though sometimes related major modes use the same one) which it
        !          13109: installs in each buffer that uses that major mode.  The syntax table
        !          13110: installed in the current buffer is the one that all commands use, so we
        !          13111: call it ``the'' syntax table.  A syntax table is a Lisp object, a vector of
        !          13112: length 256 whose elements are numbers.
        !          13113: 
        !          13114: @menu
        !          13115: * Entry: Syntax Entry.    What the syntax table records for each character.
        !          13116: * Change: Syntax Change.  How to change the information.
        !          13117: @end menu
        !          13118: 
        !          13119: @node Syntax Entry, Syntax Change, Syntax, Syntax
        !          13120: @subsection Information about Each Character
        !          13121: 
        !          13122:   The syntax table entry for a character is a number that encodes six
        !          13123: pieces of information:
        !          13124: 
        !          13125: @itemize @bullet
        !          13126: @item
        !          13127: The syntactic class of the character, represented as a small integer.
        !          13128: @item
        !          13129: The matching delimiter, for delimiter characters only.
        !          13130: The matching delimiter of @samp{(} is @samp{)}, and vice versa.
        !          13131: @item
        !          13132: A flag saying whether the character is the first character of a
        !          13133: two-character comment starting sequence.
        !          13134: @item
        !          13135: A flag saying whether the character is the second character of a
        !          13136: two-character comment starting sequence.
        !          13137: @item
        !          13138: A flag saying whether the character is the first character of a
        !          13139: two-character comment ending sequence.
        !          13140: @item
        !          13141: A flag saying whether the character is the second character of a
        !          13142: two-character comment ending sequence.
        !          13143: @end itemize
        !          13144: 
        !          13145:   The syntactic classes are stored internally as small integers, but are
        !          13146: usually described to or by the user with characters.  For example, @samp{(}
        !          13147: is used to specify the syntactic class of opening delimiters.  Here is a
        !          13148: table of syntactic classes, with the characters that specify them.
        !          13149: 
        !          13150: @table @samp
        !          13151: @item @w{ }
        !          13152: The class of whitespace characters.
        !          13153: @item -
        !          13154: Another name for the class of whitespace characters.
        !          13155: @item w
        !          13156: The class of word-constituent characters.
        !          13157: @item _
        !          13158: The class of characters that are part of symbol names but not words.
        !          13159: This class is represented by @samp{_} because the character @samp{_}
        !          13160: has this class in both C and Lisp.
        !          13161: @item .
        !          13162: The class of punctuation characters that do not fit into any other
        !          13163: special class.
        !          13164: @item (
        !          13165: The class of opening delimiters.
        !          13166: @item )
        !          13167: The class of closing delimiters.
        !          13168: @item '
        !          13169: The class of expression-adhering characters.  These characters are
        !          13170: part of a symbol if found within or adjacent to one, and are part
        !          13171: of a following expression if immediately preceding one, but are like
        !          13172: whitespace if surrounded by whitespace.
        !          13173: @item "
        !          13174: The class of string-quote characters.  They match each other in pairs,
        !          13175: and the characters within the pair all lose their syntactic
        !          13176: significance except for the @samp{\} and @samp{/} classes of escape
        !          13177: characters, which can be used to include a string-quote inside the
        !          13178: string.
        !          13179: @item $
        !          13180: The class of self-matching delimiters.  This is intended for @TeX{}'s
        !          13181: @samp{$}, which is used both to enter and leave math mode.  Thus,
        !          13182: a pair of matching @samp{$} characters surround each piece of math mode
        !          13183: @TeX{} input.  A pair of adjacent @samp{$} characters act like a single
        !          13184: one for purposes of matching.
        !          13185: 
        !          13186: @item /
        !          13187: The class of escape characters that always just deny the following
        !          13188: character its special syntactic significance.  The character after one
        !          13189: of these escapes is always treated as alphabetic.
        !          13190: @item \
        !          13191: The class of C-style escape characters.  In practice, these are
        !          13192: treated just like @samp{/}-class characters, because the extra
        !          13193: possibilities for C escapes (such as being followed by digits) have no
        !          13194: effect on where the containing expression ends.
        !          13195: @item <
        !          13196: The class of comment-starting characters.  Only single-character
        !          13197: comment starters (such as @samp{;} in Lisp mode) are represented this
        !          13198: way.
        !          13199: @item >
        !          13200: The class of comment-ending characters.  Newline has this syntax in
        !          13201: Lisp mode.
        !          13202: @end table
        !          13203: 
        !          13204: @vindex parse-sexp-ignore-comments
        !          13205:   The characters flagged as part of two-character comment delimiters can
        !          13206: have other syntactic functions most of the time.  For example, @samp{/} and
        !          13207: @samp{*} in C code, when found separately, have nothing to do with
        !          13208: comments.  The comment-delimiter significance overrides when the pair of
        !          13209: characters occur together in the proper order.  Only the list and sexp
        !          13210: commands use the syntax table to find comments; the commands specifically
        !          13211: for comments have other variables that tell them where to find comments.
        !          13212: And the list and sexp commands notice comments only if
        !          13213: @code{parse-sexp-ignore-comments} is non-@code{nil}.  This variable is set
        !          13214: to @code{nil} in modes where comment-terminator sequences are liable to
        !          13215: appear where there is no comment; for example, in Lisp mode where the
        !          13216: comment terminator is a newline but not every newline ends a comment.
        !          13217: 
        !          13218: @node Syntax Change,, Syntax Entry, Syntax
        !          13219: @subsection Altering Syntax Information
        !          13220: 
        !          13221:   It is possible to alter a character's syntax table entry by storing a new
        !          13222: number in the appropriate element of the syntax table, but it would be hard
        !          13223: to determine what number to use.  Therefore, Emacs provides a command that
        !          13224: allows you to specify the syntactic properties of a character in a
        !          13225: convenient way.
        !          13226: 
        !          13227: @findex modify-syntax-entry
        !          13228:   @kbd{M-x modify-syntax-entry} is the command to change a character's
        !          13229: syntax.  It can be used interactively, and is also the means used by major
        !          13230: modes to initialize their own syntax tables.  Its first argument is the
        !          13231: character to change.  The second argument is a string that specifies the
        !          13232: new syntax.  When called from Lisp code, there is a third, optional
        !          13233: argument, which specifies the syntax table in which to make the change.  If
        !          13234: not supplied, or if this command is called interactively, the third
        !          13235: argument defaults to the current buffer's syntax table.
        !          13236: 
        !          13237: @enumerate
        !          13238: @item
        !          13239: The first character in the string specifies the syntactic class.  It
        !          13240: is one of the characters in the previous table (@pxref{Syntax Entry}).
        !          13241: 
        !          13242: @item
        !          13243: The second character is the matching delimiter.  For a character that
        !          13244: is not an opening or closing delimiter, this should be a space, and may
        !          13245: be omitted if no following characters are needed.
        !          13246: 
        !          13247: @item
        !          13248: The remaining characters are flags.  The flag characters allowed are
        !          13249: 
        !          13250: @table @samp
        !          13251: @item 1
        !          13252: Flag this character as the first of a two-character comment starting sequence.
        !          13253: @item 2
        !          13254: Flag this character as the second of a two-character comment starting sequence.
        !          13255: @item 3
        !          13256: Flag this character as the first of a two-character comment ending sequence.
        !          13257: @item 4
        !          13258: Flag this character as the second of a two-character comment ending sequence.
        !          13259: @end table
        !          13260: @end enumerate
        !          13261: 
        !          13262: @kindex C-h s
        !          13263: @findex describe-syntax
        !          13264:   A description of the contents of the current syntax table can be
        !          13265: displayed with @kbd{C-h s} (@code{describe-syntax}).  The description of
        !          13266: each character includes both the string you would have to give to
        !          13267: @code{modify-syntax-entry} to set up that character's current syntax, and
        !          13268: some English to explain that string if necessary.
        !          13269: 
        !          13270: @node Init File,, Syntax, Customization
        !          13271: @section The Init File, .emacs
        !          13272: @cindex init file
        !          13273: @cindex Emacs initialization file
        !          13274: @cindex key rebinding, permanent
        !          13275: @cindex rebinding keys, permanently
        !          13276: 
        !          13277:   When Emacs is started, it normally loads the file @file{.emacs} in your
        !          13278: home directory.  This file, if it exists, should contain Lisp code.  It is
        !          13279: called your @dfn{init file}.  The command line switches @samp{-q} and
        !          13280: @samp{-u} can be used to tell Emacs whether to load an init file
        !          13281: (@pxref{Entering Emacs}).
        !          13282: 
        !          13283:   There can also be a @dfn{default init file}, which is the library named
        !          13284: @file{default.el}, found via the standard search path for libraries.  The
        !          13285: Emacs distribution contains no such library; your site may create one for
        !          13286: local customizations.  If this library exists, it is loaded whenever you
        !          13287: start Emacs.  But your init file, if any, is loaded first; if it sets
        !          13288: @code{inhibit-default-init} non-@code{nil}, then @file{default} is not
        !          13289: loaded.
        !          13290: 
        !          13291:   If you have a large amount of code in your @file{.emacs} file, you
        !          13292: should move it into another file named @file{@var{something}.el},
        !          13293: byte-compile it (@pxref{Lisp Libraries}), and make your @file{.emacs}
        !          13294: file load the other file using @code{load}.
        !          13295: 
        !          13296: @menu
        !          13297: * Init Syntax::     Syntax of constants in Emacs Lisp.
        !          13298: * Init Examples::   How to do some things with an init file.
        !          13299: * Terminal Init::   Each terminal type can have an init file.
        !          13300: * Debugging Init::  How to debug your @file{.emacs} file.
        !          13301: @end menu
        !          13302: 
        !          13303: @node Init Syntax, Init Examples, Init File, Init File
        !          13304: @subsection Init File Syntax
        !          13305: 
        !          13306:   The @file{.emacs} file contains one or more Lisp function call
        !          13307: expressions.  Each of these consists of a function name followed by
        !          13308: arguments, all surrounded by parentheses.  For example, @code{(setq
        !          13309: fill-column 60)} represents a call to the function @code{setq} which is
        !          13310: used to set the variable @code{fill-column} (@pxref{Filling}) to 60.
        !          13311: 
        !          13312:   The second argument to @code{setq} is an expression for the new value of
        !          13313: the variable.  This can be a constant, a variable, or a function call
        !          13314: expression.  In @file{.emacs}, constants are used most of the time.  They can be:
        !          13315: 
        !          13316: @table @asis
        !          13317: @item Numbers:
        !          13318: Numbers are written in decimal, with an optional initial minus sign.
        !          13319: 
        !          13320: @item Strings:
        !          13321: Lisp string syntax is the same as C string syntax with a few extra
        !          13322: features.  Use a double-quote character to begin and end a string constant.
        !          13323: 
        !          13324: Newlines and special characters may be present literally in strings.  They
        !          13325: can also be represented as backslash sequences: @samp{\n} for newline,
        !          13326: @samp{\b} for backspace, @samp{\r} for carriage return, @samp{\t} for tab,
        !          13327: @samp{\f} for formfeed (control-l), @samp{\e} for escape, @samp{\\} for a
        !          13328: backslash, @samp{\"} for a double-quote, or @samp{\@var{ooo}} for the
        !          13329: character whose octal code is @var{ooo}.  Backslash and double-quote are
        !          13330: the only characters for which backslash sequences are mandatory.
        !          13331: 
        !          13332: @samp{\C-} can be used as a prefix for a control character, as in
        !          13333: @w{@samp{\C-s}} for @sc{ascii} Control-S, and @samp{\M-} can be used as a prefix for
        !          13334: a meta character, as in @samp{\M-a} for Meta-A or @samp{\M-\C-a} for
        !          13335: Control-Meta-A.
        !          13336: 
        !          13337: @item Characters:
        !          13338: Lisp character constant syntax consists of a @samp{?} followed by
        !          13339: either a character or an escape sequence starting with @samp{\}.
        !          13340: Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}.  Note that
        !          13341: strings and characters are not interchangeable in Lisp; some contexts
        !          13342: require one and some contexts require the other.
        !          13343: 
        !          13344: @item True:
        !          13345: @code{t} stands for `true'.
        !          13346: 
        !          13347: @item False:
        !          13348: @code{nil} stands for `false'.
        !          13349: 
        !          13350: @item Other Lisp objects:
        !          13351: Write a single-quote (') followed by the Lisp object you want.
        !          13352: @end table
        !          13353: 
        !          13354: @node Init Examples, Terminal Init, Init Syntax, Init File
        !          13355: @subsection Init File Examples
        !          13356: 
        !          13357:   Here are some examples of doing certain commonly desired things with
        !          13358: Lisp expressions:
        !          13359: 
        !          13360: @itemize @bullet
        !          13361: @item
        !          13362: Make @key{TAB} in C mode just insert a tab if point is in the middle of a
        !          13363: line.
        !          13364: 
        !          13365: @example
        !          13366: (setq c-tab-always-indent nil)
        !          13367: @end example
        !          13368: 
        !          13369: Here we have a variable whose value is normally @code{t} for `true'
        !          13370: and the alternative is @code{nil} for `false'.
        !          13371: 
        !          13372: @item
        !          13373: Make searches case sensitive by default (in all buffers that do not
        !          13374: override this).
        !          13375: 
        !          13376: @example
        !          13377: (setq-default case-fold-search nil)
        !          13378: @end example
        !          13379: 
        !          13380: This sets the default value, which is effective in all buffers that do
        !          13381: not have local values for the variable.  Setting @code{case-fold-search}
        !          13382: with @code{setq} affects only the current buffer's local value, which
        !          13383: is not what you probably want to do in an init file.
        !          13384: 
        !          13385: @item
        !          13386: Make Text mode the default mode for new buffers.
        !          13387: 
        !          13388: @example
        !          13389: (setq default-major-mode 'text-mode)
        !          13390: @end example
        !          13391: 
        !          13392: Note that @code{text-mode} is used because it is the command for entering
        !          13393: the mode we want.  A single-quote is written before it to make a symbol
        !          13394: constant; otherwise, @code{text-mode} would be treated as a variable name.
        !          13395: 
        !          13396: @item
        !          13397: Turn on Auto Fill mode automatically in Text mode and related modes.
        !          13398: 
        !          13399: @example
        !          13400: (setq text-mode-hook
        !          13401:   '(lambda () (auto-fill-mode 1)))
        !          13402: @end example
        !          13403: 
        !          13404: Here we have a variable whose value should be a Lisp function.  The
        !          13405: function we supply is a list starting with @code{lambda}, and a single
        !          13406: quote is written in front of it to make it (for the purpose of this
        !          13407: @code{setq}) a list constant rather than an expression.  Lisp functions
        !          13408: are not explained here, but for mode hooks it is enough to know that
        !          13409: @code{(auto-fill-mode 1)} is an expression that will be executed when
        !          13410: Text mode is entered, and you could replace it with any other expression
        !          13411: that you like, or with several expressions in a row.
        !          13412: 
        !          13413: @example
        !          13414: (setq text-mode-hook 'turn-on-auto-fill)
        !          13415: @end example
        !          13416: 
        !          13417: This is another way to accomplish the same result.
        !          13418: @code{turn-on-auto-fill} is a symbol whose function definition is
        !          13419: @code{(lambda () (auto-fill-@w{mode 1}))}.
        !          13420: 
        !          13421: @item
        !          13422: Load the installed Lisp library named @file{foo} (actually a file
        !          13423: @file{foo.elc} or @file{foo.el} in a standard Emacs directory).
        !          13424: 
        !          13425: @example
        !          13426: (load "foo")
        !          13427: @end example
        !          13428: 
        !          13429: When the argument to @code{load} is a relative pathname, not starting
        !          13430: with @samp{/} or @samp{~}, @code{load} searches the directories in
        !          13431: @code{load-path} (@pxref{Loading}).
        !          13432: 
        !          13433: @item
        !          13434: Load the compiled Lisp file @file{foo.elc} from your home directory.
        !          13435: 
        !          13436: @example
        !          13437: (load "~/foo.elc")
        !          13438: @end example
        !          13439: 
        !          13440: Here an absolute file name is used, so no searching is done.
        !          13441: 
        !          13442: @item
        !          13443: Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}.
        !          13444: 
        !          13445: @example
        !          13446: (global-set-key "\C-xl" 'make-symbolic-link)
        !          13447: @end example
        !          13448: 
        !          13449: or
        !          13450: 
        !          13451: @example
        !          13452: (define-key global-map "\C-xl" 'make-symbolic-link)
        !          13453: @end example
        !          13454: 
        !          13455: Note once again the single-quote used to refer to the symbol
        !          13456: @code{make-symbolic-link} instead of its value as a variable.
        !          13457: 
        !          13458: @item
        !          13459: Do the same thing for C mode only.
        !          13460: 
        !          13461: @example
        !          13462: (define-key c-mode-map "\C-xl" 'make-symbolic-link)
        !          13463: @end example
        !          13464: 
        !          13465: @item
        !          13466: Redefine all keys which now run @code{next-line} in Fundamental mode
        !          13467: so that they run @code{forward-line} instead.
        !          13468: 
        !          13469: @example
        !          13470: (substitute-key-definition 'next-line 'forward-line
        !          13471:                            global-map)
        !          13472: @end example
        !          13473: 
        !          13474: @item
        !          13475: Make @kbd{C-x C-v} undefined.
        !          13476: 
        !          13477: @example
        !          13478: (global-unset-key "\C-x\C-v")
        !          13479: @end example
        !          13480: 
        !          13481: One reason to undefine a key is so that you can make it a prefix.
        !          13482: Simply defining @kbd{C-x C-v @var{anything}} would make @kbd{C-x C-v}
        !          13483: a prefix, but @kbd{C-x C-v} must be freed of any non-prefix definition
        !          13484: first.
        !          13485: 
        !          13486: @item
        !          13487: Make @samp{$} have the syntax of punctuation in Text mode.
        !          13488: Note the use of a character constant for @samp{$}.
        !          13489: 
        !          13490: @example
        !          13491: (modify-syntax-entry ?\$ "." text-mode-syntax-table)
        !          13492: @end example
        !          13493: 
        !          13494: @item
        !          13495: Enable the use of the command @code{eval-expression} without confirmation.
        !          13496: 
        !          13497: @example
        !          13498: (put 'eval-expression 'disabled nil)
        !          13499: @end example
        !          13500: @end itemize
        !          13501: 
        !          13502: @node Terminal Init, Debugging Init, Init Examples, Init File
        !          13503: @subsection Terminal-specific Initialization
        !          13504: 
        !          13505:   Each terminal type can have a Lisp library to be loaded into Emacs when
        !          13506: it is run on that type of terminal.  For a terminal type named
        !          13507: @var{termtype}, the library is called @file{term/@var{termtype}} and it is
        !          13508: found by searching the directories @code{load-path} as usual and trying the
        !          13509: suffixes @samp{.elc} and @samp{.el}.  Normally it appears in the
        !          13510: subdirectory @file{term} of the directory where most Emacs libraries are
        !          13511: kept.@refill
        !          13512: 
        !          13513:   The usual purpose of the terminal-specific library is to define the
        !          13514: escape sequences used by the terminal's function keys using the library
        !          13515: @file{keypad.el}.  See the file
        !          13516: @file{term/vt100.el} for an example of how this is done.@refill
        !          13517: 
        !          13518:   When the terminal type contains a hyphen, only the part of the name
        !          13519: before the first hyphen is significant in choosing the library name.
        !          13520: Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use
        !          13521: the library @file{term/aaa}.  The code in the library can use
        !          13522: @code{(getenv "TERM")} to find the full terminal type name.@refill
        !          13523: 
        !          13524: @vindex term-file-prefix
        !          13525:   The library's name is constructed by concatenating the value of the
        !          13526: variable @code{term-file-prefix} and the terminal type.  Your @file{.emacs}
        !          13527: file can prevent the loading of the terminal-specific library by setting
        !          13528: @code{term-file-prefix} to @code{nil}.
        !          13529: 
        !          13530: @vindex term-setup-hook
        !          13531:   The value of the variable @code{term-setup-hook}, if not @code{nil}, is
        !          13532: called as a function of no arguments at the end of Emacs initialization,
        !          13533: after both your @file{.emacs} file and any terminal-specific library have
        !          13534: been read in.  You can set the value in the @file{.emacs} file to override
        !          13535: part of any of the terminal-specific libraries and to define
        !          13536: initializations for terminals that do not have a library.@refill
        !          13537: 
        !          13538: @node Debugging Init,, Terminal Init, Init File
        !          13539: @subsection Debugging Your @file{.emacs} File
        !          13540: 
        !          13541:   Ordinarily, Emacs traps errors that occur while reading @file{.emacs}.
        !          13542: This is convenient, most of the time, because it means you can still get
        !          13543: an Emacs in which you can edit.  But it causes inconvenience because
        !          13544: there is no way to enter the debugger if there is an error.
        !          13545: 
        !          13546:   But you can run the @file{.emacs} file explicitly in an Emacs that is
        !          13547: already set up, and debug errors at that time.
        !          13548: 
        !          13549: @example
        !          13550: M-x set-variable
        !          13551: debug-on-error
        !          13552: t
        !          13553: M-x load-file
        !          13554: ~/.emacs
        !          13555: @end example
        !          13556: 
        !          13557:   In Emacs 19, use the @samp{-debug-init} option if you want errors in
        !          13558: @file{.emacs} to enter the debugger.
        !          13559: 
        !          13560: @iftex
        !          13561: @chapter Correcting Mistakes (Yours or Emacs's)
        !          13562: 
        !          13563:   If you type an Emacs command you did not intend, the results are often
        !          13564: mysterious.  This chapter tells what you can do to cancel your mistake or
        !          13565: recover from a mysterious situation.  Emacs bugs and system crashes are
        !          13566: also considered.
        !          13567: @end iftex
        !          13568: 
        !          13569: @node Quitting, Lossage, Customization, Top
        !          13570: @section Quitting and Aborting
        !          13571: @cindex quitting
        !          13572: 
        !          13573: @table @kbd
        !          13574: @item C-g
        !          13575: Quit.  Cancel running or partially typed command.
        !          13576: @item C-]
        !          13577: Abort innermost recursive editing level and cancel the command which
        !          13578: invoked it (@code{abort-recursive-edit}).
        !          13579: @item M-x top-level
        !          13580: Abort all recursive editing levels that are currently executing.
        !          13581: @item C-x u
        !          13582: Cancel an already-executed command, usually (@code{undo}).
        !          13583: @end table
        !          13584: 
        !          13585:   There are two ways of cancelling commands which are not finished
        !          13586: executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]}
        !          13587: or @kbd{M-x top-level}.  Quitting is cancelling a partially typed command
        !          13588: or one which is already running.  Aborting is getting out of a recursive
        !          13589: editing level and cancelling the command that invoked the recursive edit.
        !          13590: 
        !          13591: @cindex quitting
        !          13592: @cindex C-g
        !          13593:   Quitting with @kbd{C-g} is used for getting rid of a partially typed
        !          13594: command, or a numeric argument that you don't want.  It also stops a
        !          13595: running command in the middle in a relatively safe way, so you can use it
        !          13596: if you accidentally give a command which takes a long time.  In particular,
        !          13597: it is safe to quit out of killing; either your text will @var{all} still be
        !          13598: there, or it will @var{all} be in the kill ring (or maybe both).  Quitting
        !          13599: an incremental search does special things documented under searching; in
        !          13600: general, it may take two successive @kbd{C-g} characters to get out of a
        !          13601: search.  @kbd{C-g} works by setting the variable @code{quit-flag} to
        !          13602: @code{t} the instant @kbd{C-g} is typed; Emacs Lisp checks this variable
        !          13603: frequently and quits if it is non-@code{nil}.  @kbd{C-g} is only actually
        !          13604: executed as a command if it is typed while Emacs is waiting for input.
        !          13605: 
        !          13606:   If you quit twice in a row before the first @kbd{C-g} is recognized, you
        !          13607: activate the ``emergency escape'' feature and return to the shell.
        !          13608: @xref{Emergency Escape}.
        !          13609: 
        !          13610: @cindex recursive editing level
        !          13611: @cindex editing level, recursive
        !          13612: @cindex aborting
        !          13613: @findex abort-recursive-edit
        !          13614: @kindex C-]
        !          13615:   Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get out
        !          13616: of a recursive editing level and cancel the command which invoked it.
        !          13617: Quitting with @kbd{C-g} does not do this, and could not do this, because it
        !          13618: is used to cancel a partially typed command @i{within} the recursive
        !          13619: editing level.  Both operations are useful.  For example, if you are in the
        !          13620: Emacs debugger (@pxref{Lisp Debug}) and have typed @kbd{C-u 8} to enter a
        !          13621: numeric argument, you can cancel that argument with @kbd{C-g} and remain in
        !          13622: the debugger.
        !          13623: 
        !          13624: @findex top-level
        !          13625:   The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]}
        !          13626: commands to get you out of all the levels of recursive edits that you are
        !          13627: in.  @kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level}
        !          13628: goes out all levels at once.  Both @kbd{C-]} and @kbd{M-x top-level} are
        !          13629: like all other commands, and unlike @kbd{C-g}, in that they are effective
        !          13630: only when Emacs is ready for a command.  @kbd{C-]} is an ordinary key and
        !          13631: has its meaning only because of its binding in the keymap.
        !          13632: @xref{Recursive Edit}.
        !          13633: 
        !          13634:   @kbd{C-x u} (@code{undo}) is not strictly speaking a way of cancelling a
        !          13635: command, but you can think of it as cancelling a command already finished
        !          13636: executing.  @xref{Undo}.
        !          13637: 
        !          13638: @node Lossage, Bugs, Quitting, Top
        !          13639: @section Dealing with Emacs Trouble
        !          13640: 
        !          13641:   This section describes various conditions in which Emacs fails to work,
        !          13642: and how to recognize them and correct them.
        !          13643: 
        !          13644: @menu
        !          13645: * Stuck Recursive::    `[...]' in mode line around the parentheses
        !          13646: * Screen Garbled::     Garbage on the screen
        !          13647: * Text Garbled::       Garbage in the text
        !          13648: * Unasked-for Search:: Spontaneous entry to incremental search
        !          13649: * Emergency Escape::   Emergency escape---
        !          13650:                         What to do if Emacs stops responding
        !          13651: * Total Frustration::  When you are at your wits' end.
        !          13652: @end menu
        !          13653: 
        !          13654: @node Stuck Recursive, Screen Garbled, Lossage, Lossage
        !          13655: @subsection Recursive Editing Levels
        !          13656: 
        !          13657:   Recursive editing levels are important and useful features of Emacs, but
        !          13658: they can seem like malfunctions to the user who does not understand them.
        !          13659: 
        !          13660:   If the mode line has square brackets @samp{[@dots{}]} around the parentheses
        !          13661: that contain the names of the major and minor modes, you have entered a
        !          13662: recursive editing level.  If you did not do this on purpose, or if you
        !          13663: don't understand what that means, you should just get out of the recursive
        !          13664: editing level.  To do so, type @kbd{M-x top-level}.  This is called getting
        !          13665: back to top level.  @xref{Recursive Edit}.
        !          13666: 
        !          13667: @node Screen Garbled, Text Garbled, Stuck Recursive, Lossage
        !          13668: @subsection Garbage on the Screen
        !          13669: 
        !          13670:   If the data on the screen looks wrong, the first thing to do is see
        !          13671: whether the text is really wrong.  Type @kbd{C-l}, to redisplay the entire
        !          13672: screen.  If it appears correct after this, the problem was entirely in the
        !          13673: previous screen update.
        !          13674: 
        !          13675:   Display updating problems often result from an incorrect termcap entry
        !          13676: for the terminal you are using.  The file @file{etc/TERMS} in the Emacs
        !          13677: distribution gives the fixes for known problems of this sort.
        !          13678: @file{INSTALL} contains general advice for these problems in one of its
        !          13679: sections.  Very likely there is simply insufficient padding for certain
        !          13680: display operations.  To investigate the possibility that you have this sort
        !          13681: of problem, try Emacs on another terminal made by a different manufacturer.
        !          13682: If problems happen frequently on one kind of terminal but not another kind,
        !          13683: it is likely to be a bad termcap entry, though it could also be due to a
        !          13684: bug in Emacs that appears for terminals that have or that lack specific
        !          13685: features.
        !          13686: 
        !          13687: @node Text Garbled, Unasked-for Search, Screen Garbled, Lossage
        !          13688: @subsection Garbage in the Text
        !          13689: 
        !          13690:   If @kbd{C-l} shows that the text is wrong, try undoing the changes to it
        !          13691: using @kbd{C-x u} until it gets back to a state you consider correct.  Also
        !          13692: try @kbd{C-h l} to find out what command you typed to produce the observed
        !          13693: results.
        !          13694: 
        !          13695:   If a large portion of text appears to be missing at the beginning or
        !          13696: end of the buffer, check for the word @samp{Narrow} in the mode line.
        !          13697: If it appears, the text is still present, but marked off-limits.
        !          13698: To make it visible again, type @kbd{C-x w}.  @xref{Narrowing}.
        !          13699: 
        !          13700: @node Unasked-for Search, Emergency Escape, Text Garbled, Lossage
        !          13701: @subsection Spontaneous Entry to Incremental Search
        !          13702: 
        !          13703:   If Emacs spontaneously displays @samp{I-search:} at the bottom of the
        !          13704: screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q}
        !          13705: according to the poorly designed @samp{xon/xoff} ``flow control''
        !          13706: protocol.  You should try to prevent this by putting the terminal in a
        !          13707: mode where it will not use flow control or giving it enough padding
        !          13708: that it will never send a @kbd{C-s}.  If that cannot be done, you must
        !          13709: tell Emacs to expect flow control to be used, until you can get a
        !          13710: properly designed terminal.
        !          13711: 
        !          13712:   Information on how to do these things can be found in the file
        !          13713: @file{INSTALL} in the Emacs distribution.
        !          13714: 
        !          13715: @node Emergency Escape, Total Frustration, Unasked-for Search, Lossage
        !          13716: @subsection Emergency Escape
        !          13717: 
        !          13718:   Because at times there have been bugs causing Emacs to loop without
        !          13719: checking @code{quit-flag}, a special feature causes Emacs to be suspended
        !          13720: immediately if you type a second @kbd{C-g} while the flag is already set,
        !          13721: so you can always get out of GNU Emacs.  Normally Emacs recognizes and
        !          13722: clears @code{quit-flag} (and quits!) quickly enough to prevent this from
        !          13723: happening.
        !          13724: 
        !          13725:   When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it
        !          13726: asks two questions before going back to what it had been doing:
        !          13727: 
        !          13728: @example
        !          13729: Auto-save? (y or n)
        !          13730: Abort (and dump core)? (y or n)
        !          13731: @end example
        !          13732: 
        !          13733: @noindent
        !          13734: Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}.
        !          13735: 
        !          13736:   Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all
        !          13737: modified buffers in which auto-saving is enabled.
        !          13738: 
        !          13739:   Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be
        !          13740: executed, dumping core.  This is to enable a wizard to figure out why Emacs
        !          13741: was failing to quit in the first place.  Execution does not continue
        !          13742: after a core dump.  If you answer @kbd{n}, execution does continue.  With
        !          13743: luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally.
        !          13744: If not, and you type another @kbd{C-g}, it is suspended again.
        !          13745: 
        !          13746:   If Emacs is not really hung, just slow, you may invoke the double
        !          13747: @kbd{C-g} feature without really meaning to.  Then just resume and answer
        !          13748: @kbd{n} to both questions, and you will arrive at your former state.
        !          13749: Presumably the quit you requested will happen soon.
        !          13750: 
        !          13751:   The double-@kbd{C-g} feature may be turned off when Emacs is running under
        !          13752: a window system, since the window system always enables you to kill Emacs
        !          13753: or to create another window and run another program.
        !          13754: 
        !          13755: @node Total Frustration,, Emergency Escape, Lossage
        !          13756: @subsection Help for Total Frustration
        !          13757: @cindex Eliza
        !          13758: @cindex doctor
        !          13759: 
        !          13760:   If using Emacs (or something else) becomes terribly frustrating and none
        !          13761: of the techniques described above solve the problem, Emacs can still help
        !          13762: you.
        !          13763: 
        !          13764:   First, if the Emacs you are using is not responding to commands, type
        !          13765: @kbd{C-g C-g} to get out of it and then start a new one.
        !          13766: 
        !          13767: @findex doctor
        !          13768:   Second, type @kbd{M-x doctor @key{RET}}.
        !          13769: 
        !          13770:   The doctor will make you feel better.  Each time you say something to
        !          13771: the doctor, you must end it by typing @key{RET} @key{RET}.  This lets the
        !          13772: doctor know you are finished.
        !          13773: 
        !          13774: @node Bugs, Version 19, Lossage, Top
        !          13775: @section Reporting Bugs
        !          13776: 
        !          13777: @cindex bugs
        !          13778:   Sometimes you will encounter a bug in Emacs.  Although we cannot promise
        !          13779: we can or will fix the bug, and we might not even agree that it is a bug,
        !          13780: we want to hear about bugs you encounter in case we do want to fix them.
        !          13781: 
        !          13782:   To make it possible for us to fix a bug, you must report it.  In order
        !          13783: to do so effectively, you must know when and how to do it.
        !          13784: 
        !          13785: @subsection When Is There a Bug
        !          13786: 
        !          13787:   If Emacs executes an illegal instruction, or dies with an operating
        !          13788: system error message that indicates a problem in the program (as opposed to
        !          13789: something like ``disk full''), then it is certainly a bug.
        !          13790: 
        !          13791:   If Emacs updates the display in a way that does not correspond to what is
        !          13792: in the buffer, then it is certainly a bug.  If a command seems to do the
        !          13793: wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a
        !          13794: case of incorrect display updating.
        !          13795: 
        !          13796:   Taking forever to complete a command can be a bug, but you must make
        !          13797: certain that it was really Emacs's fault.  Some commands simply take a long
        !          13798: time.  Type @kbd{C-g} and then @kbd{C-h l} to see whether the input Emacs
        !          13799: received was what you intended to type; if the input was such that you
        !          13800: @var{know} it should have been processed quickly, report a bug.  If you
        !          13801: don't know whether the command should take a long time, find out by looking
        !          13802: in the manual or by asking for assistance.
        !          13803: 
        !          13804:   If a command you are familiar with causes an Emacs error message in a
        !          13805: case where its usual definition ought to be reasonable, it is probably a
        !          13806: bug.
        !          13807: 
        !          13808:   If a command does the wrong thing, that is a bug.  But be sure you know
        !          13809: for certain what it ought to have done.  If you aren't familiar with the
        !          13810: command, or don't know for certain how the command is supposed to work,
        !          13811: then it might actually be working right.  Rather than jumping to
        !          13812: conclusions, show the problem to someone who knows for certain.
        !          13813: 
        !          13814:   Finally, a command's intended definition may not be best for editing
        !          13815: with.  This is a very important sort of problem, but it is also a matter of
        !          13816: judgment.  Also, it is easy to come to such a conclusion out of ignorance
        !          13817: of some of the existing features.  It is probably best not to complain
        !          13818: about such a problem until you have checked the documentation in the usual
        !          13819: ways, feel confident that you understand it, and know for certain that what
        !          13820: you want is not available.  If you are not sure what the command is
        !          13821: supposed to do after a careful reading of the manual, check the index and
        !          13822: glossary for any terms that may be unclear.  If you still do not
        !          13823: understand, this indicates a bug in the manual.  The manual's job is to
        !          13824: make everything clear.  It is just as important to report documentation
        !          13825: bugs as program bugs.
        !          13826: 
        !          13827:   If the on-line documentation string of a function or variable disagrees
        !          13828: with the manual, one of them must be wrong, so report the bug.
        !          13829: 
        !          13830: @subsection How to Report a Bug
        !          13831: 
        !          13832: @cindex version of Emacs
        !          13833: @cindex Emacs version
        !          13834: @findex emacs-version
        !          13835:   When you decide that there is a bug, it is important to report it and to
        !          13836: report it in a way which is useful.  What is most useful is an exact
        !          13837: description of what commands you type, starting with the shell command to
        !          13838: run Emacs, until the problem happens.  Always include the version number
        !          13839: of Emacs that you are using; type @kbd{M-x emacs-version} to print this.
        !          13840: 
        !          13841:   The most important principle in reporting a bug is to report @var{facts},
        !          13842: not hypotheses or categorizations.  It is always easier to report the facts,
        !          13843: but people seem to prefer to strain to posit explanations and report
        !          13844: them instead.  If the explanations are based on guesses about how Emacs is
        !          13845: implemented, they will be useless; we will have to try to figure out what
        !          13846: the facts must have been to lead to such speculations.  Sometimes this is
        !          13847: impossible.  But in any case, it is unnecessary work for us.
        !          13848: 
        !          13849:   For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh
        !          13850: @key{RET}}, visiting a file which (you know) happens to be rather large,
        !          13851: and Emacs prints out @samp{I feel pretty today}.  The best way to report
        !          13852: the bug is with a sentence like the preceding one, because it gives all the
        !          13853: facts and nothing but the facts.
        !          13854: 
        !          13855:   Do not assume that the problem is due to the size of the file and say,
        !          13856: ``When I visit a large file, Emacs prints out @samp{I feel pretty today}.''
        !          13857: This is what we mean by ``guessing explanations''.  The problem is just as
        !          13858: likely to be due to the fact that there is a @samp{z} in the file name.  If
        !          13859: this is so, then when we got your report, we would try out the problem with
        !          13860: some ``large file'', probably with no @samp{z} in its name, and not find
        !          13861: anything wrong.  There is no way in the world that we could guess that we
        !          13862: should try visiting a file with a @samp{z} in its name.
        !          13863: 
        !          13864:   Alternatively, the problem might be due to the fact that the file starts
        !          13865: with exactly 25 spaces.  For this reason, you should make sure that you
        !          13866: inform us of the exact contents of any file that is needed to reproduce the
        !          13867: bug.  What if the problem only occurs when you have typed the @kbd{C-x C-a}
        !          13868: command previously?  This is why we ask you to give the exact sequence of
        !          13869: characters you typed since starting to use Emacs.
        !          13870: 
        !          13871:   You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless
        !          13872: you @i{know} that it makes no difference which visiting command is used.
        !          13873: Similarly, rather than saying ``if I have three characters on the line,''
        !          13874: say ``after I type @w{@kbd{@key{RET} A B C} @key{RET} C-p},'' if that is
        !          13875: the way you entered the text.
        !          13876: 
        !          13877:   If you are not in Fundamental mode when the problem occurs, you should
        !          13878: say what mode you are in.
        !          13879: 
        !          13880:   If the manifestation of the bug is an Emacs error message, it is
        !          13881: important to report not just the text of the error message but a backtrace
        !          13882: showing how the Lisp program in Emacs arrived at the error.  To make the
        !          13883: backtrace, you must execute the Lisp expression 
        !          13884: @code{(setq @w{debug-on-error t})} before the error happens (that is to
        !          13885: say, you must execute that expression and then make the bug happen).  This
        !          13886: causes the Lisp debugger to run (@pxref{Lisp Debug}).  The debugger's
        !          13887: backtrace can be copied as text into the bug report.  This use of the
        !          13888: debugger is possible only if you know how to make the bug happen again.  Do
        !          13889: note the error message the first time the bug happens, so if you can't make
        !          13890: it happen again, you can report at least that.
        !          13891: 
        !          13892:   Check whether any programs you have loaded into the Lisp world, including
        !          13893: your @file{.emacs} file, set any variables that may affect the functioning
        !          13894: of Emacs.  Also, see whether the problem happens in a freshly started Emacs
        !          13895: without loading your @file{.emacs} file (start Emacs with the @code{-q} switch
        !          13896: to prevent loading the init file.)  If the problem does @var{not} occur
        !          13897: then, it is essential that we know the contents of any programs that you
        !          13898: must load into the Lisp world in order to cause the problem to occur.
        !          13899: 
        !          13900:   If the problem does depend on an init file or other Lisp programs that
        !          13901: are not part of the standard Emacs system, then you should make sure it is
        !          13902: not a bug in those programs by complaining to their maintainers first.
        !          13903: After they verify that they are using Emacs in a way that is supposed to
        !          13904: work, they should report the bug.
        !          13905: 
        !          13906:   If you can tell us a way to cause the problem without visiting any files,
        !          13907: please do so.  This makes it much easier to debug.  If you do need files,
        !          13908: make sure you arrange for us to see their exact contents.  For example, it
        !          13909: can often matter whether there are spaces at the ends of lines, or a
        !          13910: newline after the last line in the buffer (nothing ought to care whether
        !          13911: the last line is terminated, but tell that to the bugs).
        !          13912: 
        !          13913: @findex open-dribble-file
        !          13914: @cindex dribble file
        !          13915:   The easy way to record the input to Emacs precisely is to write a
        !          13916: dribble file; execute the Lisp expression
        !          13917: 
        !          13918: @example
        !          13919: (open-dribble-file "~/dribble")
        !          13920: @end example
        !          13921: 
        !          13922: @noindent
        !          13923: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just after starting
        !          13924: Emacs.  From then on, all Emacs input will be written in the specified
        !          13925: dribble file until the Emacs process is killed.
        !          13926: 
        !          13927: @findex open-termscript
        !          13928: @cindex termscript file
        !          13929:   For possible display bugs, it is important to report the terminal type
        !          13930: (the value of environment variable @code{TERM}), the complete termcap entry
        !          13931: for the terminal from @file{/etc/termcap} (since that file is not identical
        !          13932: on all machines), and the output that Emacs actually sent to the terminal.
        !          13933: The way to collect this output is to execute the Lisp expression
        !          13934: 
        !          13935: @example
        !          13936: (open-termscript "~/termscript")
        !          13937: @end example
        !          13938: 
        !          13939: @noindent
        !          13940: using @kbd{Meta-@key{ESC}} or from the @samp{*scratch*} buffer just
        !          13941: after starting Emacs.  From then on, all output from Emacs to the terminal
        !          13942: will be written in the specified termscript file as well, until the Emacs
        !          13943: process is killed.  If the problem happens when Emacs starts up, put this
        !          13944: expression into your @file{.emacs} file so that the termscript file will
        !          13945: be open when Emacs displays the screen for the first time.  Be warned:
        !          13946: it is often difficult, and sometimes impossible, to fix a terminal-dependent
        !          13947: bug without access to a terminal of the type that stimulates the bug.@refill
        !          13948: 
        !          13949:   The address for reporting bugs is
        !          13950: 
        !          13951: @format
        !          13952: GNU Emacs Bugs
        !          13953: Free Software Foundation
        !          13954: 675 Mass Ave
        !          13955: Cambridge, MA 02139
        !          13956: @end format
        !          13957: 
        !          13958: @noindent
        !          13959: or send email either to @samp{bug-gnu-emacs@@prep.ai.mit.edu} (Internet)
        !          13960: or to @samp{uunet!prep.ai.mit.edu!bug-gnu-emacs} (Usenet).
        !          13961: 
        !          13962:   Once again, we do not promise to fix the bug; but if the bug is serious,
        !          13963: or ugly, or easy to fix, chances are we will want to.
        !          13964: 
        !          13965: @node Version 19, Manifesto, Bugs, Top
        !          13966: @unnumbered Version 19 Antenews
        !          13967: 
        !          13968: This chapter prematurely describes new features of Emacs 19, in
        !          13969: anticipation of its release.  We have included this so that the version
        !          13970: 18 manuals don't become obsolete as soon as Emacs 19 comes out.  This
        !          13971: list mentions only features that would belong in @cite{The GNU Emacs
        !          13972: Manual}; changes relevant to Emacs Lisp programming will be documented
        !          13973: in the next revision of @cite{The GNU Emacs Lisp Manual}.
        !          13974: 
        !          13975: @menu
        !          13976: * Basic Changes::        Changes every user must know.
        !          13977: * New Facilities::       Changes every user will want to know.
        !          13978: * Binding Changes::      Ordinary commands that have been moved.  Important!.
        !          13979: * Changed Commands::     Ordinary commands that have new features.  Important!
        !          13980: * M-x Changes::                  Changes in commands you run with @kbd{M-x}.  Important!
        !          13981: * New Commands::         Commands that have been added
        !          13982:                            that we expect many users to want to use.
        !          13983: * Search Changes::       Changes in incremental search.  Some are important.
        !          13984: 
        !          13985: The rest of the changes you can pretty much ignore unless you are interested.
        !          13986: 
        !          13987: * Filling Changes::      Changes in fill commands.
        !          13988: * TeX Mode Changes::     Changes in the commands for editing TeX files
        !          13989:                            and running TeX.
        !          13990: * Shell Changes::        Major changes in all the modes that run subprograms.
        !          13991: * Spell Changes::        These commands now use ispell instead of spell.
        !          13992: * Tags Changes::         Changes in Tags facility.
        !          13993: * Mail Changes::         Changes in both Sendmail mode and Rmail mode.
        !          13994: * Info Changes::         New commands in Info.
        !          13995: * Dired Changes::        Powerful new features in Dired.
        !          13996: * GNUS::                 An alternative news reader.
        !          13997: * Calendar/Diary::       The calendar feature now lets you move to different
        !          13998:                            dates and convert to and from other calendars.
        !          13999:                          You can also display related entries from your diary
        !          14000:                            file.
        !          14001: * Version Control::      A convenient interface to RCS or SCCS.
        !          14002: * Emerge::               A new feature for merging files interactively.
        !          14003: * Debuggers::            Running debuggers (GDB, DBX, SDB) under Emacs.
        !          14004: * Other New Modes::      Miscellaneous new and changed major modes.
        !          14005: * Key Sequence Changes::  You can now bind key sequences that include function
        !          14006:                            keys and mouse clicks.
        !          14007: * Hook Changes::         Hook variables have been renamed more systematically.
        !          14008: @end menu
        !          14009: 
        !          14010: @node Basic Changes
        !          14011: @section Basic Changes
        !          14012: 
        !          14013: We have made changes to help Emacs use fewer resources and make it less
        !          14014: likely to become irreparably hung.  While these changes don't alter the
        !          14015: commands of Emacs, they are important enough to be worth mentioning.
        !          14016: 
        !          14017: You can quit with @kbd{C-g} while Emacs is waiting to read or write a
        !          14018: file---provided the operating system will allow you to interrupt the
        !          14019: system call that is hung.  (Unfortunately, most NFS implementations
        !          14020: won't allow interruption.)
        !          14021: 
        !          14022: When you kill buffers, Emacs now returns memory to the operating system,
        !          14023: thus reducing the size of the Emacs process.  The space that you free up
        !          14024: by killing buffers can now be reused for other buffers no matter what
        !          14025: their sizes, or reused by other processes if Emacs doesn't need it.
        !          14026: 
        !          14027: @subheading Multiple X Windows
        !          14028: 
        !          14029: When using X windows, you can now create more than one window at the X
        !          14030: level.  Each X window displays a @dfn{frame} which can contain one or
        !          14031: several Emacs windows.  Each frame has its own echo area and normally
        !          14032: its own minibuffer.  (To avoid confusion, we reserve the word
        !          14033: ``window'' for the subdivisions that Emacs implements, and never use
        !          14034: it to refer to a frame.)  The easiest way to create additional frames
        !          14035: is with the @kbd{C-x 5} prefix character (@pxref{New Commands, , New
        !          14036: Everyday Commands}).
        !          14037: 
        !          14038: @c ??? Change not yet made
        !          14039: @findex scroll-bar-mode @r{(V19)}
        !          14040: Emacs windows can now have scroll bars; use the @code{scroll-bar-mode}
        !          14041: command to turn scroll bars on or off.  With no argument, it toggles the
        !          14042: use of scroll bars.  With an argument, it turns use of scroll bars on if
        !          14043: and only if the argument is positive.  This command applies to all
        !          14044: frames, including frames yet to be created.  (You can control scroll
        !          14045: bars on a frame by frame basis by writing a Lisp program.)
        !          14046: 
        !          14047: @subheading Undo Improvements
        !          14048: 
        !          14049: @c ??? Change not yet made
        !          14050: Undoing a deletion now puts the cursor position where it was just before
        !          14051: the deletion.
        !          14052: 
        !          14053: @subheading Auto Save Improvements
        !          14054: 
        !          14055: @vindex auto-save-timeout @r{(V19)}
        !          14056: Emacs now does garbage collection and auto saving while it is waiting
        !          14057: for input, which often avoids the need to do these things while you are
        !          14058: typing.  The variable @code{auto-save-timeout} says how many seconds
        !          14059: Emacs should wait, after you stop typing, before it does an auto save
        !          14060: and perhaps also a garbage collection.  (The actual time period varies
        !          14061: also according to the size of the buffer---longer for longer buffers,
        !          14062: since auto saving itself is slower for long buffers.)  This way, Emacs
        !          14063: does not interrupt or delay your typing.
        !          14064: 
        !          14065: In Emacs 18, when auto saving detects that a buffer has shrunk greatly,
        !          14066: it refrains from auto saving that buffer and displays a warning.  In
        !          14067: version 19, it also turns off Auto Save mode in that buffer, so that you
        !          14068: won't get the same warning repeatedly.  If you reenable Auto Save mode
        !          14069: in that buffer, Emacs will start saving it again despite the shrinkage.
        !          14070: 
        !          14071: @findex revert-buffer @r{(V19)}
        !          14072: In Emacs 19, @code{revert-buffer} no longer offers to revert from the
        !          14073: latest auto-save file.  That option hasn't been very useful since the
        !          14074: change to keep more undo information.
        !          14075: 
        !          14076: The command @code{recover-file} no longer turns off Auto Save mode.
        !          14077: 
        !          14078: @subheading File Local Variables
        !          14079: 
        !          14080: @vindex enable-local-variables @r{(V19)}
        !          14081: @vindex inhibit-local-variables @r{(V19)}
        !          14082: The user option for controlling whether files can set local variables is
        !          14083: called @code{enable-local-variables} in Emacs 19, rather than
        !          14084: @code{inhibit-local-variables}.  A value of @code{t} means
        !          14085: local-variables lists are obeyed; @code{nil} means they are ignored;
        !          14086: anything else means query the user.
        !          14087: 
        !          14088: @node New Facilities
        !          14089: @section New Basic Facilities
        !          14090: 
        !          14091: @cindex minibuffer history
        !          14092: @cindex history, in minibuffer
        !          14093: @kindex M-p @r{(V19)}
        !          14094: @kindex M-n @r{(V19)}
        !          14095: @findex next-history-element @r{(V19)}
        !          14096: @findex previous-history-element @r{(V19)}
        !          14097: You can now get back recent minibuffer inputs conveniently.  While in
        !          14098: the minibuffer, type @kbd{M-p} (@code{previous-history-element}) to fetch
        !          14099: the next earlier minibuffer input, and use @kbd{M-n}
        !          14100: (@code{next-history-element}) to fetch the next later input.
        !          14101: 
        !          14102: @findex previous-matching-history-element @r{(V19)}
        !          14103: @findex next-matching-history-element @r{(V19)}
        !          14104: @kindex M-r @r{(V19)}
        !          14105: @kindex M-s @r{(V19)}
        !          14106: There are also commands to search forward or backward through the
        !          14107: history.  As of this writing, they search for history elements that
        !          14108: match a regular expression that you specify with the minibuffer.
        !          14109: @kbd{M-r} (@code{previous-matching-history-element}) searches older
        !          14110: elements in the history, while @kbd{M-s}
        !          14111: (@code{next-matching-history-element}) searches newer elements.  By
        !          14112: special dispensation, these commands can always use the minibuffer to
        !          14113: read their arguments even though you are already in the minibuffer when
        !          14114: you issue them.
        !          14115: 
        !          14116: We may have changed the precise way these commands work by the time you
        !          14117: use Emacs 19.  Perhaps they will search for a match for the string given
        !          14118: so far in the minibuffer; perhaps they will search for a literal match
        !          14119: rather than a regular expression match; perhaps they will only accept
        !          14120: matches at the beginning of a history element; perhaps they will read
        !          14121: the string to search for incrementally like @kbd{C-s}.  We want to
        !          14122: choose an interface that is convenient, flexible and natural, and these
        !          14123: goals are somewhat contradictory.  To find out what interface is
        !          14124: actually available, type @kbd{C-h f previous-matching-history-element}.
        !          14125: 
        !          14126: The history feature is available for all uses of the minibuffer, but
        !          14127: there are separate history lists for different kinds of input.  For
        !          14128: example, there is a list for file names, used by all the commands that
        !          14129: read file names.  There is a list for arguments of commands like
        !          14130: @code{query-replace}.  There are also very specific history lists, such
        !          14131: as the one that @code{compile} uses for compilation commands.
        !          14132: 
        !          14133: @subheading Remote File Access
        !          14134: 
        !          14135: @cindex ftp
        !          14136: @cindex remote file access
        !          14137: You can refer to files on other machines using a special file name syntax:
        !          14138: 
        !          14139: @example
        !          14140: @group
        !          14141: /@var{host}:@var{filename}
        !          14142: /@var{user}@@@var{host}:@var{filename}
        !          14143: @end group
        !          14144: @end example
        !          14145: 
        !          14146: When you do this, Emacs uses the FTP program to read and write files on
        !          14147: the specified host.  It logs in through FTP using your user name or the
        !          14148: name @var{user}.  It may ask you for a password from time to time; this
        !          14149: is used for logging in on @var{host}.
        !          14150: 
        !          14151: @subheading Using Flow Control
        !          14152: 
        !          14153: @cindex flow control in V19
        !          14154: @cindex xon-xoff in V19
        !          14155: There is now a convenient way to enable flow control when your terminal
        !          14156: or your connection won't work without it.  Suppose you want to do this
        !          14157: on VT-100 and H19 terminals; put the following in your @file{.emacs}
        !          14158: file:
        !          14159: 
        !          14160: @findex evade-flow-control-on @r{(V19)}
        !          14161: @example
        !          14162: (evade-flow-control-on "vt100" "h19")
        !          14163: @end example
        !          14164: 
        !          14165: When flow control is enabled, you must type @kbd{C-\} to get the effect
        !          14166: of a @kbd{C-s}, and type @kbd{C-^} to get the effect of a @kbd{C-q}.
        !          14167: 
        !          14168: @subheading Controlling Backup File Names
        !          14169: 
        !          14170: @vindex version-control @r{(V19)}
        !          14171: @vindex VERSION_CONTROL
        !          14172: The default setting of the Lisp variable @code{version-control} now
        !          14173: comes from the environment variable @code{VERSION_CONTROL}.  Thus, you
        !          14174: can select a style of backup file naming for Emacs and other GNU
        !          14175: utilities all together.
        !          14176: 
        !          14177: @node Binding Changes
        !          14178: @section Changed Key Bindings
        !          14179: 
        !          14180: @table @kbd
        !          14181: @item M-@{
        !          14182: @kindex M-@{ @r{(V19)}
        !          14183: This is the new key sequence for @code{backward-paragraph}.  The old key
        !          14184: sequence for this, @kbd{M-[}, is now undefined by default.
        !          14185: 
        !          14186: The reason for this change is to avoid conflict with the sequences that
        !          14187: function keys send on most terminals.
        !          14188: 
        !          14189: @item M-@}
        !          14190: @kindex M-@} @r{(V19)}
        !          14191: This is the new key sequence for @code{forward-paragraph}.  The old key
        !          14192: sequence for this, @kbd{M-]}, is now undefined by default.
        !          14193: 
        !          14194: We changed this to go along with @kbd{M-@{}.
        !          14195: 
        !          14196: @item C-x C-u
        !          14197: @itemx C-x C-l
        !          14198: @kindex C-x C-u @r{(V19)}
        !          14199: @kindex C-x C-l @r{(V19)}
        !          14200: The two commands, @kbd{C-x C-u} (@code{upcase-region}) and @kbd{C-x
        !          14201: C-l} (@code{downcase-region}), are now disabled by default; these
        !          14202: keys seem to be often hit by accident, and can be quite
        !          14203: destructive if their effects are not noticed immediately.
        !          14204: 
        !          14205: @item C-x 3
        !          14206: @kindex C-x 3 @r{(V19)}
        !          14207: @kbd{C-x 3} is now the key binding for @code{split-window-horizontally},
        !          14208: which splits a window into two side-by-side windows.  This used to be
        !          14209: @kbd{C-x 5}.
        !          14210: 
        !          14211: @item @kbd{C-x 4 C-o}
        !          14212: @kindex C-x 4 C-o @r{(V19)}
        !          14213: @findex display-buffer @r{(V19)}
        !          14214: This key now runs @code{display-buffer}, which displays a specified
        !          14215: buffer in another window without selecting it.
        !          14216: 
        !          14217: @item M-g
        !          14218: @kindex M-g @r{(V19)}
        !          14219: @kbd{M-g} is now undefined.  It used to run the command @code{fill-region}.
        !          14220: This command used to be run more often by mistake than on purpose.
        !          14221: 
        !          14222: @item C-x a
        !          14223: @itemx C-x n
        !          14224: @itemx C-x r
        !          14225: @kindex C-x a @r{(V19)}
        !          14226: @kindex C-x n @r{(V19)}
        !          14227: @kindex C-x r @r{(V19)}
        !          14228: Three new prefix keys have been created to make many of the @w{@kbd{C-x}}
        !          14229: commands more systematic: @w{@kbd{C-x a}}, @w{@kbd{C-x n}} and @w{@kbd{C-x r}}.
        !          14230: @w{@kbd{C-x a}} is used for abbreviation commands, @w{@kbd{C-x n}} for commands
        !          14231: pertaining to narrowing, and @w{@kbd{C-x r}} for register and rectangle
        !          14232: commands.  These are the new bindings, in detail:
        !          14233: 
        !          14234: @table @kbd
        !          14235: @item C-x a l
        !          14236: @code{add-mode-abbrev} (previously @kbd{C-x C-a}).
        !          14237: @item C-x a g
        !          14238: @code{add-global-abbrev} (previously @kbd{C-x +}).
        !          14239: @item C-x a i g
        !          14240: @code{inverse-add-mode-abbrev} (previously @kbd{C-x C-h}).
        !          14241: @item C-x a i l
        !          14242: @code{inverse-add-global-abbrev} (previously @kbd{C-x -}).
        !          14243: @item C-x a e
        !          14244: @code{expand-abbrev} (previously @kbd{C-x '}).
        !          14245: 
        !          14246: @sp 1
        !          14247: 
        !          14248: @item C-x n n
        !          14249: @code{narrow-to-region} (previously @kbd{C-x n}).
        !          14250: @item C-x n p
        !          14251: @code{narrow-to-page} (previously @kbd{C-x p}).
        !          14252: @item C-x n w
        !          14253: @code{widen} (previously @kbd{C-x w}).
        !          14254: 
        !          14255: @sp 1
        !          14256: 
        !          14257: @item C-x r C-@key{SPC}
        !          14258: @code{point-to-register} (previously @kbd{C-x /}).
        !          14259: @item C-x r @key{SPC}
        !          14260: Also @code{point-to-register} (previously @kbd{C-x /}).
        !          14261: @item C-x r j
        !          14262: @code{jump-to-register} (previously @kbd{C-x j}).
        !          14263: @item C-x r s
        !          14264: @code{copy-to-register} (previously @kbd{C-x x}).
        !          14265: @item C-x r i
        !          14266: @code{insert-register} (previously @kbd{C-x g}).
        !          14267: @item C-x r r
        !          14268: @code{copy-rectangle-to-register} (previously @kbd{C-x r}).
        !          14269: @item C-x r k
        !          14270: @code{kill-rectangle} (no previous key binding).
        !          14271: @item C-x r y
        !          14272: @code{yank-rectangle} (no previous key binding).
        !          14273: @item C-x r o
        !          14274: @code{open-rectangle} (no previous key binding).
        !          14275: @item C-x r f
        !          14276: @code{frame-configuration-to-register} (a new command)
        !          14277: saves the state of all windows in all frames.
        !          14278: Use @kbd{C-x r j} to restore the configuration.
        !          14279: @c !!! following generates acceptable underfull hbox
        !          14280: @item C-x r w
        !          14281: @code{window-configuration-to-register} (a new command)
        !          14282: saves the state of all windows in the selected  frame.
        !          14283: Use @kbd{C-x r j} to restore the configuration.
        !          14284: @end table
        !          14285: 
        !          14286: The old key bindings @kbd{C-x /}, @kbd{C-x j}, @kbd{C-x x} and @kbd{C-x
        !          14287: g} have not yet been removed.  The other old key bindings listed have
        !          14288: been removed.  The old key binding @kbd{C-x a}, which was
        !          14289: @code{append-to-buffer}, was removed to make way for a prefix key; now
        !          14290: @code{append-to-buffer} has no keybinding.
        !          14291: 
        !          14292: @item C-x v
        !          14293: @kbd{C-x v} is a new prefix character, used for version control commands.
        !          14294: @xref{Version Control}.
        !          14295: @end table
        !          14296: 
        !          14297: @node Changed Commands
        !          14298: @section Changed Everyday Commands
        !          14299: 
        !          14300: @table @kbd
        !          14301: @item C-o
        !          14302: @kindex C-o @r{(V19)}
        !          14303: When you have a fill prefix, the command @kbd{C-o} inserts the prefix on
        !          14304: the newly created line.
        !          14305: 
        !          14306: @item M-^
        !          14307: @kindex M-^ @r{(V19)}
        !          14308: When you have a fill prefix, the command @kbd{M-^} deletes the prefix
        !          14309: (if it occurs) after the newline that it deletes.
        !          14310: 
        !          14311: @item M-z
        !          14312: @kindex M-z @r{(V19)}
        !          14313: The @kbd{M-z} command (@code{zap-to-char}) now kills through the target
        !          14314: character.  In version 18, it killed up to but not including the target
        !          14315: character.
        !          14316: 
        !          14317: @item M-!
        !          14318: @kindex M-! @r{(V19)}
        !          14319: The command @kbd{M-!} (@code{shell-command}) now runs the specified
        !          14320: shell command asynchronously if it ends in @samp{&}, just as the shell
        !          14321: does.
        !          14322: 
        !          14323: @item C-x 2
        !          14324: @kindex C-x 2 @r{(V19)}
        !          14325: @vindex split-window-keep-point @r{(V19)}
        !          14326: The @kbd{C-x 2} command (@code{split-window-vertically}) now tries to
        !          14327: avoid scrolling by putting point in whichever window happens to contain
        !          14328: the screen line the cursor is already on.  If you don't like this, you
        !          14329: can turn it off by setting @code{split-window-keep-point} to
        !          14330: @code{nil}.
        !          14331: 
        !          14332: @item C-x s
        !          14333: @kindex C-x s @r{(V19)}
        !          14334: The @kbd{C-x s} command (@code{save-some-buffers}) now gives you more
        !          14335: options when it asks whether to save a particular buffer.  The options
        !          14336: are analogous to those of @code{query-replace}.  Here they are:
        !          14337: 
        !          14338: @table @kbd
        !          14339: @item y
        !          14340: Save this buffer and ask about the rest of the buffers.
        !          14341: @item n
        !          14342: Don't save this buffer, but ask about the rest of the buffers.
        !          14343: @item !
        !          14344: Save this buffer and all the rest with no more questions.
        !          14345: @c !!! following generates acceptable underfull hbox
        !          14346: @item @key{ESC}
        !          14347: Terminate @code{save-some-buffers} without any more saving.
        !          14348: @item .
        !          14349: @c !!! following written verbosely to avoid overfull hbox
        !          14350: Save only this buffer, then exit @code{save-some-buffers} without even asking
        !          14351: about other buffers.
        !          14352: @item C-r
        !          14353: View the buffer that you are currently being asked about.  When you exit
        !          14354: View mode, you get back to @code{save-some-buffers}, which asks the
        !          14355: question again.
        !          14356: @item C-h
        !          14357: Display a help message about these options.
        !          14358: @end table
        !          14359: 
        !          14360: @item C-x C-v
        !          14361: @kindex C-x C-v @r{(V19)}
        !          14362: This command (@kbd{find-alternate-file}) now inserts the entire current
        !          14363: file name in the minibuffer.  This is convenient if you made a small
        !          14364: mistake in typing it.  Point goes after the last slash, before the last
        !          14365: file name component, so if you want to replace it entirely, you can use
        !          14366: @kbd{C-k} right away to delete it.
        !          14367: 
        !          14368: @item C-M-f
        !          14369: @kindex C-M-f @r{(V19)}
        !          14370: Expression and list commands such as @kbd{C-M-f} now ignore parentheses
        !          14371: within comments in Lisp mode.
        !          14372: @end table
        !          14373: 
        !          14374: @node M-x Changes
        !          14375: @section Changes in Common @kbd{M-x} Commands
        !          14376: 
        !          14377: @table @asis
        !          14378: @item @kbd{M-x make-symbolic-link}
        !          14379: @findex make-symbolic-link @r{(V19)}
        !          14380: This command now does not expand its second argument.  This lets you
        !          14381: make a link with a target that is a relative file name.
        !          14382: 
        !          14383: @item @kbd{M-x add-change-log-entry}
        !          14384: @itemx @kbd{C-x 4 a}
        !          14385: @findex add-change-log-entry @r{(V19)}
        !          14386: @kindex C-x 4 a @r{(V19)}
        !          14387: These commands now automatically insert the name of the file and often
        !          14388: the name of the function that you changed.  They also handle grouping of
        !          14389: entries.
        !          14390: 
        !          14391: There is now a special major mode for editing @file{ChangeLog} files.
        !          14392: It makes filling work conveniently.  Each bunch of grouped entries is
        !          14393: one paragraph, and each collection of entries from one person on one day
        !          14394: is considered a page.
        !          14395: 
        !          14396: @item @kbd{M-x compare-windows}
        !          14397: @findex compare-windows @r{(V19)}
        !          14398: With a prefix argument, @code{compare-windows} ignores changes in
        !          14399: whitespace.  If the variable @code{compare-ignore-case} is
        !          14400: non-@code{nil}, it ignores differences in case as well.
        !          14401: 
        !          14402: @item @kbd{M-x view-buffer}
        !          14403: @itemx @kbd{M-x view-file}
        !          14404: @findex view-buffer @r{(V19)}
        !          14405: @findex view-file @r{(V19)}
        !          14406: The View commands (such as @kbd{M-x view-buffer} and @kbd{M-x
        !          14407: view-file}) no longer use recursive edits; instead, they switch
        !          14408: temporarily to a different major mode (View mode) specifically designed
        !          14409: for moving around through a buffer without editing it.
        !          14410: 
        !          14411: @item @kbd{M-x manual-entry}
        !          14412: @findex manual-entry @r{(V19)}
        !          14413: @kbd{M-x manual-entry} now uses View mode for the buffer showing the
        !          14414: man page.
        !          14415: 
        !          14416: @item @kbd{M-x compile}
        !          14417: @findex compile @r{(V19)}
        !          14418: You can repeat any previous @code{compile} conveniently using the
        !          14419: minibuffer history commands, while in the minibuffer entering the
        !          14420: compilation command.
        !          14421: 
        !          14422: While a compilation is going on, the string @samp{Compiling} appears
        !          14423: in the mode line.  When this string disappears, the compilation is
        !          14424: finished.
        !          14425: 
        !          14426: The buffer of compiler messages is in Compilation mode.  This mode
        !          14427: provides the keys @key{SPC} and @key{DEL} to scroll by screenfuls, and
        !          14428: @kbd{M-n} and @kbd{M-p} to move to the next or previous error message.
        !          14429: You can also use @kbd{M-@{} and @kbd{M-@}} to move up or down to an
        !          14430: error message for a different source file.  Use @kbd{C-c C-c} on any
        !          14431: error message to find the corresponding source code.
        !          14432: 
        !          14433: Emacs 19 has a more general parser for compiler messages.  For example, it
        !          14434: can understand messages from lint, and from certain C compilers whose
        !          14435: error message format is unusual.
        !          14436: @end table
        !          14437: 
        !          14438: @node New Commands
        !          14439: @section New Everyday Commands
        !          14440: 
        !          14441: @table @asis
        !          14442: @item @kbd{C-z}
        !          14443: @kindex C-z @r{(V19)}
        !          14444: @findex iconify-frame @r{(V19)}
        !          14445: When you are using X windows, @kbd{C-z} (@code{iconify-frame}) now
        !          14446: iconifies the current frame.
        !          14447: 
        !          14448: @item @kbd{C-M-l}
        !          14449: @kindex C-M-l @r{(V19)}
        !          14450: @findex reposition-window @r{(V19)}
        !          14451: The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current
        !          14452: window heuristically in a way designed to get useful information onto
        !          14453: the screen.  For example, in a Lisp file, this command tries to get the
        !          14454: entire current defun onto the screen if possible.
        !          14455: 
        !          14456: @item @kbd{C-M-r}
        !          14457: @kindex C-M-r @r{(V19)}
        !          14458: @findex isearch-backward-regexp @r{(V19)}
        !          14459: @c !!! following written verbosely to avoid overfull hbox
        !          14460: The @kbd{C-M-r} key now runs the command @code{isearch-backward-regexp},
        !          14461: which does reverse incremental regexp search.
        !          14462: 
        !          14463: @item @kbd{C-x 5}
        !          14464: @kindex C-x 5 @r{(V19)}
        !          14465: The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with parallel
        !          14466: subcommands.  The difference is that @kbd{C-x 5} commands create a new
        !          14467: frame rather than just a new window.
        !          14468: 
        !          14469: @item @kbd{C-x 5 C-f}
        !          14470: @itemx @kbd{C-x 5 b}
        !          14471: @kindex C-x 5 C-f @r{(V19)}
        !          14472: @kindex C-x 5 b @r{(V19)}
        !          14473: @findex find-file-other-frame @r{(V19)}
        !          14474: @findex switch-to-buffer-other-frame @r{(V19)}
        !          14475: These new commands switch to a specified file or buffer in a new frame
        !          14476: (when using X windows).  The commands' names are
        !          14477: @code{find-file-other-frame} and @code{switch-to-buffer-other-frame}.
        !          14478: 
        !          14479: @item @kbd{C-x 5 m}
        !          14480: @kindex C-x 5 m @r{(V19)}
        !          14481: @findex mail-other-frame @r{(V19)}
        !          14482: Start outgoing mail in another frame (@code{mail-other-frame}).
        !          14483: 
        !          14484: @item @kbd{C-x 5 .}
        !          14485: @kindex C-x 5 . @r{(V19)}
        !          14486: @findex find-tag-other-frame @r{(V19)}
        !          14487: Find a tag in another frame (@code{find-tag-other-frame}).
        !          14488: 
        !          14489: @item @kbd{C-x 4 r}
        !          14490: @kindex C-x 4 r @r{(V19)}
        !          14491: @findex find-file-read-only-other-window @r{(V19)}
        !          14492: This is now @code{find-file-read-only-other-window}.
        !          14493: 
        !          14494: @item arrow keys
        !          14495: @cindex arrow keys
        !          14496: The arrow keys now have default bindings to move in the appropriate
        !          14497: directions.
        !          14498: 
        !          14499: @item @kbd{C-h C-f}
        !          14500: @itemx @kbd{C-h C-k}
        !          14501: @kindex C-h C-f @r{(V19)}
        !          14502: @kindex C-h C-k @r{(V19)}
        !          14503: These new help commands enter Info and display the node for a given
        !          14504: Emacs function name or key sequence, respectively.
        !          14505: 
        !          14506: @item @kbd{M-a}
        !          14507: @itemx @kbd{M-e}
        !          14508: @kindex M-a @r{(C mode in V19)}
        !          14509: @kindex M-e @r{(C mode in V19)}
        !          14510: @findex c-beginning-of-statement @r{(V19)}
        !          14511: @findex c-end-of-statement @r{(V19)}
        !          14512: In C mode, @kbd{M-a} and @kbd{M-e} now move by complete C statements
        !          14513: (@code{c-beginning-of-statement} and @code{c-end-of-statement}).
        !          14514: 
        !          14515: @item @kbd{M-q}
        !          14516: @kindex M-q @r{(C mode in V19)}
        !          14517: @findex c-fill-paragraph @r{(V19)}
        !          14518: @kbd{M-q} in C mode now runs @code{c-fill-paragraph}, which is designed
        !          14519: for filling C comments.  (We assume you don't want to fill the actual C
        !          14520: code in a C program.)
        !          14521: 
        !          14522: @item @kbd{M-x c-up-conditional}
        !          14523: @findex c-up-conditional @r{(V19)}
        !          14524: In C mode, @code{c-up-conditional} moves back to the containing
        !          14525: preprocessor conditional, setting the mark where point was previously.
        !          14526: 
        !          14527: A prefix argument acts as a repeat count.  With a negative argument,
        !          14528: this command moves forward to the end of the containing preprocessor
        !          14529: conditional.  When going backwards, @samp{#elif} acts like @samp{#else}
        !          14530: followed by @samp{#if}.  When going forwards, @samp{#elif} is ignored.
        !          14531: 
        !          14532: @item @kbd{M-x comment-region}
        !          14533: @findex comment-region @r{(V19)}
        !          14534: The @code{comment-region} command adds comment delimiters to the lines
        !          14535: that start in the region, thus commenting them out.  With a negative
        !          14536: argument, it deletes comment delimiters from the lines in the
        !          14537: region---this is the inverse of the effect of @code{comment-region}
        !          14538: without an argument.
        !          14539: 
        !          14540: With a positive argument, @code{comment-region} adds comment delimiters
        !          14541: but duplicates the last character of the comment start sequence as many
        !          14542: times as the argument specifies.  This is a way of calling attention to
        !          14543: the comment.  In Lisp, you should use an argument of at least two, because
        !          14544: the indentation convention for single semicolon comments does not leave
        !          14545: them at the beginning of a line.
        !          14546: 
        !          14547: @item @kbd{M-x super-apropos}
        !          14548: @findex super-apropos @r{(V19)}
        !          14549: This command is like @code{apropos} except that it searches for a
        !          14550: regular expression instead of merely a substring.
        !          14551: 
        !          14552: @findex apropros @r{(V19)}
        !          14553: @kindex C-h a @r{(V19)}
        !          14554: If you use a prefix argument (regardless of its value) with
        !          14555: @code{apropos} or @code{super-apropos}, they also search documentation
        !          14556: strings for matches as well as symbol names.  The prefix argument also
        !          14557: controls looking up and printing the key bindings of all commands.
        !          14558: 
        !          14559: @item @kbd{M-x diff}
        !          14560: @findex diff @r{(V19)}
        !          14561: @vindex diff-switches @r{(V19)}
        !          14562: This new command compares two files, displaying the differences in an
        !          14563: Emacs buffer.  The options for the @code{diff} program come from the
        !          14564: variable @code{diff-switches}, whose value should be a string.
        !          14565: 
        !          14566: The buffer of differences has Compilation mode as its major mode, so you
        !          14567: can use @kbd{C-x `} to visit successive changed locations in the two
        !          14568: source files, or you can move to a particular hunk of changes and type
        !          14569: @kbd{C-c C-c} to move to the corresponding source.  You can also use the
        !          14570: other special commands of Compilation mode: @key{SPC} and @key{DEL} for
        !          14571: scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion.
        !          14572: 
        !          14573: @item @kbd{M-x diff-backup}
        !          14574: @findex diff-backup @r{(V19)}
        !          14575: The command @code{diff-backup} compares a specified file with its most
        !          14576: recent backup.  If you specify the name of a backup file,
        !          14577: @code{diff-backup} compares it with the source file that it is a backup
        !          14578: of.
        !          14579: @end table
        !          14580: 
        !          14581: @node Search Changes
        !          14582: @section Changes in Incremental Search
        !          14583: 
        !          14584: The most important change in incremental search is that @key{RET} now
        !          14585: terminates a search, and @key{ESC} does not.  The other changes are
        !          14586: useful, but not vital to know about.
        !          14587: 
        !          14588: @cindex Incremental search in V19
        !          14589: @findex isearch @r{(V19)}
        !          14590: @itemize @bullet
        !          14591: @item
        !          14592: The character to terminate an incremental search is now @key{RET}.  This
        !          14593: is for compatibility with the way most other arguments are read.
        !          14594: 
        !          14595: To search for a newline in an incremental search, type @key{LFD} (also
        !          14596: known as @kbd{C-j}).
        !          14597: 
        !          14598: (This change is somewhat of an experiment; it might be taken back by
        !          14599: the time Emacs 19 is really released.)
        !          14600: 
        !          14601: @item
        !          14602: Incremental search now maintains a ring of previous search strings.  Use
        !          14603: @kbd{M-p} and @kbd{M-n} to move through the ring to pick a search string
        !          14604: to reuse.  These commands leave the selected search ring element in the
        !          14605: minibuffer, where you can edit it.  Type @key{RET} to finish editing and
        !          14606: search for the chosen string.
        !          14607: 
        !          14608: @item
        !          14609: When there is an upper-case letter in the search
        !          14610: string, then the search is case sensitive.
        !          14611: 
        !          14612: @item
        !          14613: Incremental search is now implemented as a major mode.  When you type
        !          14614: @kbd{C-s}, it switches temporarily to a different keymap which defines
        !          14615: each key to do what it ought to do for incremental search.  This has
        !          14616: next to no effect on the user-visible behavior of searching, but makes
        !          14617: it easier to customize that behavior.
        !          14618: @end itemize
        !          14619: 
        !          14620: @node Filling Changes
        !          14621: @section Changes in Fill Commands
        !          14622: 
        !          14623: @itemize @bullet
        !          14624: @item
        !          14625: @findex fill-individual-paragraphs @r{(V19)}
        !          14626: @code{fill-individual-paragraphs} now has two modes.  Its default mode
        !          14627: is that any change in indentation starts a new paragraph.  The alternate
        !          14628: mode is that only separator lines separate paragraphs; this can handle
        !          14629: paragraphs with extra indentation on the first line.  To select the
        !          14630: alternate mode, set @code{fill-individual-varying-indent} to a
        !          14631: non-@code{nil} value.
        !          14632: 
        !          14633: @item
        !          14634: @cindex Adaptive Fill mode
        !          14635: @findex fill-region-as-paragraph @r{(V19)}
        !          14636: Filling is now partially controlled by a new minor mode, Adaptive Fill
        !          14637: mode.  When this mode is enabled (and it is enabled by default), if you
        !          14638: use @code{fill-region-as-paragraph} on an indented paragraph and you
        !          14639: don't have a fill prefix, it uses the indentation of the second line of
        !          14640: the paragraph as the fill prefix.
        !          14641: 
        !          14642: Adaptive Fill mode doesn't have much effect on @kbd{M-q} in most major
        !          14643: modes, because an indented line will probably count as a paragraph
        !          14644: starter and thus each line of an indented paragraph will be considered
        !          14645: a paragraph of its own.
        !          14646: 
        !          14647: @item
        !          14648: @kindex M-q @r{(C mode in V19)}
        !          14649: @findex c-fill-paragraph @r{(V19)}
        !          14650: @kbd{M-q} in C mode now runs @code{c-fill-paragraph}, which is designed
        !          14651: for filling C comments.  (We assume you don't want to fill the actual C
        !          14652: code in a C program.)
        !          14653: @end itemize
        !          14654: 
        !          14655: @node TeX Mode Changes
        !          14656: @section Changes in @TeX{} Mode
        !          14657: 
        !          14658: @cindex Tex mode in V19
        !          14659: @kindex C-c @{ @r{(TeX mode in V19)}
        !          14660: @kindex C-c @} @r{(TeX mode in V19)}
        !          14661: The old @TeX{} mode bindings of @kbd{M-@{} and @kbd{M-@}} have been
        !          14662: moved to @kbd{C-c @{} and @kbd{C-c @}}.  (These commands are
        !          14663: @code{up-list} and @code{tex-insert-braces}; they are the @TeX{}
        !          14664: equivalents of @kbd{M-(} and @kbd{M-)}.)
        !          14665: 
        !          14666: @c !!! following generates acceptable underfull hbox
        !          14667: @kindex C-c C-e @r{(TeX mode in V19)}
        !          14668: @kindex C-c C-o @r{(TeX mode in V19)}
        !          14669: @findex tex-latex-block @r{(V19)}
        !          14670: @findex tex-close-latex-block @r{(V19)}
        !          14671: The new command @kbd{C-c C-o} (@code{tex-latex-block}) inserts a
        !          14672: matching @samp{\begin}--@samp{\end} pair.  The new command @kbd{C-c C-e}
        !          14673: (@code{tex-close-latex-block}) inserts a matching @samp{\end} for the
        !          14674: last unterminated @samp{\begin}.
        !          14675: 
        !          14676: @kindex C-c @key{TAB} @r{(TeX mode in V19)}
        !          14677: @findex tex-bibtex-file @r{(V19)}
        !          14678: You can run Bib@TeX{} on the current file using @kbd{C-c @key{TAB}}
        !          14679: (@code{tex-bibtex-file}).
        !          14680: 
        !          14681: @kindex C-c C-v @r{(TeX mode in V19)}
        !          14682: @findex tex-view @r{(V19)}
        !          14683: There is a new command @kbd{C-c C-v} (@code{tex-view}) for running a
        !          14684: DVI previewer.
        !          14685: 
        !          14686: @vindex tex-directory @r{(V19)}
        !          14687: You can specify the directory to use for running @TeX{} by setting the
        !          14688: variable @code{tex-directory}.  @code{"."} is the default value.  If
        !          14689: your environment variable @code{TEXINPUTS} contains relative directory
        !          14690: names, or if your files contains @samp{\input} commands with relative
        !          14691: file names, then @code{tex-directory} @emph{must} be @code{"."} or you
        !          14692: will get the wrong results.  Otherwise, it is safe to specify some other
        !          14693: directory, such as @file{/tmp}.
        !          14694: 
        !          14695: There is now a third variant of @TeX{} mode, for Sli@TeX{}.  This is in
        !          14696: addition to the variants for plain @TeX{} and La@TeX{}.  As before, the
        !          14697: correct variant is chosen automatically when you visit a file.
        !          14698: 
        !          14699: @node Shell Changes
        !          14700: @section Changes in Shell Mode
        !          14701: 
        !          14702: @cindex Shell mode in V19
        !          14703: Shell mode has been completely replaced with a new implementation.
        !          14704: The basic idea is the same: Emacs runs a subshell, and all input
        !          14705: and output to the subshell go through the shell buffer.  But the
        !          14706: special commands of Shell mode have been redesigned.
        !          14707:       
        !          14708: @table @kbd
        !          14709: @item @key{TAB}
        !          14710: @kindex @key{TAB} @r{(Shell mode in V19)}
        !          14711: @findex comint-dynamic-complete @r{(V19)}
        !          14712: Complete the file name before point in the shell buffer
        !          14713: (@code{comint-dynamic-complete}).
        !          14714: 
        !          14715: @item M-?
        !          14716: @kindex M-? @r{(Shell mode in V19)}
        !          14717: @findex comint-dynamic-list-completions @r{(V19)}
        !          14718: To get a list of all possible completions of the file name before, type
        !          14719: @kbd{M-?}  (@code{comint-dynamic-list-completions}).
        !          14720: 
        !          14721: @item M-p
        !          14722: @itemx M-n
        !          14723: @kindex M-p @r{(Shell mode in V19)}
        !          14724: @kindex M-n @r{(Shell mode in V19)}
        !          14725: @findex comint-next-input @r{(V19)}
        !          14726: @findex comint-previous-input @r{(V19)}
        !          14727: There is a new convenient history mechanism for repeating previous
        !          14728: shell inputs.  Use the command @kbd{M-p} (@code{comint-previous-input}) to
        !          14729: recall the last input; it copies the text of that input to the place
        !          14730: where you are editing.  If you repeat @w{@kbd{M-p}}, it replaces the copied
        !          14731: input with successively earlier inputs.  @kbd{M-n} is similar but goes in the
        !          14732: opposite direction, towards the present (@code{comint-next-input}).
        !          14733: 
        !          14734: When you find the previous input you want, you can resubmit it by typing
        !          14735: @key{RET}, or you can edit it first and then resubmit it if you wish.
        !          14736: 
        !          14737: These shell history commands operate outside the minibuffer, but they
        !          14738: are completely analogous to the minibuffer history commands.
        !          14739: 
        !          14740: @item M-r
        !          14741: @itemx M-s
        !          14742: @kindex M-r @r{(Shell mode in V19)}
        !          14743: @kindex M-s @r{(Shell mode in V19)}
        !          14744: @findex comint-previous-matching-input @r{(V19)}
        !          14745: @findex comint-next-matching-input @r{(V19)}
        !          14746: You can also use @kbd{M-r} and @kbd{M-s} to search for (respectively)
        !          14747: earlier or later inputs starting with a given string.  First type the
        !          14748: string, then type @kbd{M-r} (@code{comint-previous-matching-input}) to
        !          14749: yank a previous input from the history which starts with that string.
        !          14750: You can repeat @kbd{M-r} to find successively earlier inputs starting
        !          14751: with the same string.
        !          14752: 
        !          14753: You can start moving in the opposite direction (toward more recent
        !          14754: inputs) by typing @kbd{M-s} (@code{comint-next-matching-input}) instead
        !          14755: of @kbd{M-r}.  As long as you don't use any commands except @kbd{M-r}
        !          14756: and @kbd{M-s}, they keep using the same string that you had entered
        !          14757: initially.
        !          14758: 
        !          14759: These commands serve a purpose similar to that of @kbd{M-r} and
        !          14760: @kbd{M-s} in the minibuffer, but do not work in quite the same way.  We
        !          14761: may change the interface of these commands, as well as that of the
        !          14762: analogous minibuffer commands; one goal will be to make the two sets of
        !          14763: commands compatible.  But we haven't yet figured out which of the
        !          14764: possible interfaces is best.  To find out what interface is actually
        !          14765: supported in Emacs 19, type @kbd{C-h f comint-previous-matching-input
        !          14766: @key{RET}}.
        !          14767: 
        !          14768: @item C-c C-o
        !          14769: @kindex C-c C-o @r{(Shell mode in V19)}
        !          14770: @findex comint-kill-output @r{(V19)}
        !          14771: Kill the last batch of output from a shell command
        !          14772: (@code{comint-kill-output}).  This is useful if a shell command spews
        !          14773: out lots of output that just gets in the way.
        !          14774: 
        !          14775: @item C-c C-r
        !          14776: @kindex C-c C-r @r{(Shell mode in V19)}
        !          14777: @findex comint-show-output @r{(V19)}
        !          14778: Scroll to display the
        !          14779: beginning of the last batch of output at the top of the window; it also
        !          14780: moves the cursor there (@code{comint-show-output}).
        !          14781: 
        !          14782: @item C-a
        !          14783: @kindex C-a @r{(Shell mode in V19)}
        !          14784: If you type @kbd{C-a} on a line that starts with a shell prompt, it
        !          14785: moves to the end of the prompt, not to the very beginning of the line.
        !          14786: 
        !          14787: @item C-d
        !          14788: @kindex C-d @r{(Shell mode in V19)}
        !          14789: Typed at the end of the shell buffer, @kbd{C-d} sends EOF to the
        !          14790: subshell.  Typed at any other position in the buffer, @kbd{C-d}
        !          14791: deletes a character as usual.
        !          14792: 
        !          14793: @item M-x dirs
        !          14794: @findex dirs @r{(V19)}
        !          14795: If Emacs gets confused while trying to track changes in the shell's
        !          14796: current directory, type @kbd{M-x dirs} to re-synchronize.
        !          14797: 
        !          14798: @item M-x send-invisible
        !          14799: @findex send-invisible @r{(V19)}
        !          14800: This command reads a line of text without echoing it, and sends it to
        !          14801: the shell.
        !          14802: 
        !          14803: @item M-x comint-continue-subjob
        !          14804: @findex comint-continue-subjob @r{(V19)}
        !          14805: If you accidentally suspend your process, use this command to continue it.
        !          14806: @end table
        !          14807: 
        !          14808: @node Spell Changes
        !          14809: @section Changes in Spell Checking
        !          14810: 
        !          14811: @cindex Spell checking in V19
        !          14812: @cindex @code{ispell} program @r{(V19)}
        !          14813: @findex kill-ispell @r{(V19)}
        !          14814: Emacs 19 uses the Ispell program for spelling correction instead of the
        !          14815: Unix spell program.  Ispell has many advantages; one is that it can be
        !          14816: started the first time you check a word, and left running thereafter,
        !          14817: which makes further checking much faster.  If you want to get rid of the
        !          14818: Ispell process, use @kbd{M-x kill-ispell}.
        !          14819: 
        !          14820: @findex ispell-buffer @r{(V19)}
        !          14821: @findex ispell-region @r{(V19)}
        !          14822: To check the entire current buffer, use @kbd{M-x ispell-buffer}.  Use
        !          14823: @kbd{M-x ispell-region} to check just the current region.
        !          14824: 
        !          14825: @kindex M-$ @r{(V19)}
        !          14826: Ispell commands often involve interactive replacement of words.
        !          14827: You can interrupt the interactive replacement with @kbd{C-g}.
        !          14828: You can restart it again afterward with @kbd{C-u M-$}.
        !          14829: 
        !          14830: Interactive replacement shows you one misspelling at a time and asks you
        !          14831: what to do.  To answer, type one of the following characters:
        !          14832: 
        !          14833: @table @kbd
        !          14834: @item @var{digit}
        !          14835: Replace the word (this time) with one of the displayed near-misses.
        !          14836: The digit you use says which near-miss to use.
        !          14837: 
        !          14838: @item a
        !          14839: Accept this word this time.
        !          14840: 
        !          14841: @item i
        !          14842: Insert this word in your private dictionary
        !          14843: so that Ispell will consider it correct it from now on.
        !          14844: 
        !          14845: @item r
        !          14846: Replace the word this time with a string typed by you.
        !          14847: @end table
        !          14848: 
        !          14849: When the Ispell process starts, it reads your private dictionary which
        !          14850: is the file @file{~/ispell.words}.  Words that you ``insert'' with the
        !          14851: @kbd{i} command are added to that file, but not right away---only at the
        !          14852: end of the interactive replacement procedure.
        !          14853: 
        !          14854: @c !!! Written verbosely to avoid overfull hbox.
        !          14855: @findex reload-ispell @r{(V19)}
        !          14856: Use the @kbd{M-x reload-ispell} command
        !          14857: to reload your private dictionary from
        !          14858: @file{~/ispell.words} if you edit the file outside of Ispell.
        !          14859: 
        !          14860: @node Mail Changes
        !          14861: @section Changes in Mail Reading and Sending
        !          14862: 
        !          14863: @cindex Mail mode in V19
        !          14864: @samp{%} is now a word-separator character in Mail mode.  This is because
        !          14865: that character frequently appears in addresses.
        !          14866: 
        !          14867: @vindex mail-signature @r{(V19)}
        !          14868: If you set the variable @code{mail-signature} non-@code{nil}, then
        !          14869: @code{mail} inserts the contents of your @file{.signature} file
        !          14870: automatically when it initializes a mail buffer.  If you don't want your
        !          14871: signature in a particular message, just delete it from the buffer before
        !          14872: you send the message.
        !          14873: 
        !          14874: @vindex mail-yank-prefix @r{(V19)}
        !          14875: You can specify the text to insert at the beginning of each line when
        !          14876: you use @kbd{C-c C-y} to yank the message you are replying to.  Set
        !          14877: @code{mail-yank-prefix} to the desired string.  A value of @code{nil}
        !          14878: (the default) means to use indentation, as in Emacs 18.  If you use
        !          14879: @kbd{C-u} by itself as the prefix argument to @kbd{C-c C-y}, then it
        !          14880: does not insert anything at the beginning of the lines, regardless of
        !          14881: the value of @code{mail-yank-prefix}.
        !          14882: 
        !          14883: @findex unrmail
        !          14884: You can easily convert an Rmail file to system mailbox format with the
        !          14885: command @code{unrmail}.  This command reads two arguments, the name of
        !          14886: the Rmail file to convert, and the name of the new mailbox file.
        !          14887: The Rmail file is unchanged by this command.
        !          14888: 
        !          14889: @cindex Rmail in V19
        !          14890: Rmail now initially positions you at the first message in the Rmail file
        !          14891: that you have not seen.  This may not be a message that just arrived; it
        !          14892: may have arrived in a previous session during which you did not select
        !          14893: it.  You can then read all the unseen messages going forwards.
        !          14894: 
        !          14895: @kindex C-M-m @r{(Rmail in V19)}
        !          14896: @findex rmail-retry-failure @r{(V19)}
        !          14897: When a message that you sent ``bounces'' back to you, you can retry
        !          14898: sending it by typing @kbd{C-M-m} (@code{rmail-retry-failure}) on the
        !          14899: failure message.
        !          14900: 
        !          14901: @findex rmail-resend @r{(V19)}
        !          14902: By contrast, the new command @kbd{M-x rmail-resend} is used for
        !          14903: forwarding a message and marking it as ``resentby'' you,
        !          14904: with the special header fields @samp{Resent-by:} and @samp{Resent-to:}.
        !          14905: 
        !          14906: @kindex < @r{(Rmail in V19)}
        !          14907: Another new Rmail command is @kbd{<}, which moves to the first message.
        !          14908: (This is for symmetry with @kbd{>}.)  @kbd{<} is actually an alias for
        !          14909: @kbd{j}.
        !          14910: 
        !          14911: @kindex e @r{(Rmail in V19)}
        !          14912: @kindex x @r{(Rmail in V19)}
        !          14913: @c !!!! overfull hbox cured by ugly change
        !          14914: @kbd{e} (@code{rmail-edit-current-message}) is now the command
        !          14915: to edit a message.  To expunge, type @kbd{x}.  We know
        !          14916: this will surprise people some of the time, but the surprise will not be
        !          14917: disastrous---if you type @kbd{e} meaning to expunge, just type @kbd{C-c
        !          14918: C-c} to leave Rmail Edit mode, and then type @kbd{x}.
        !          14919: 
        !          14920: @vindex rmail-output-file-alist
        !          14921: The variable @code{rmail-output-file-alist} now controls the default
        !          14922: for the file to output a message to.
        !          14923: 
        !          14924: @kindex C-n @r{(Rmail summary in V19)}
        !          14925: @kindex C-p @r{(Rmail summary in V19)}
        !          14926: @kindex M-n @r{(Rmail summary in V19)}
        !          14927: @kindex M-p @r{(Rmail summary in V19)}
        !          14928: @kindex p @r{(Rmail summary in V19)}
        !          14929: @kindex n @r{(Rmail summary in V19)}
        !          14930: In the Rmail summary, @kbd{C-n} and @kbd{C-p} are now ordinary cursor
        !          14931: motion commands.  To move in the summary @emph{and} select a new
        !          14932: message, use @kbd{n} and @kbd{p} (which skip deleted messages) or
        !          14933: @kbd{M-n} and @kbd{M-p} (which stop at all messages).  These are, of
        !          14934: course, the same commands you would use in the Rmail buffer.
        !          14935: 
        !          14936: @node Tags Changes
        !          14937: @section Changes in Tags Commands
        !          14938: 
        !          14939: @cindex tags in V19
        !          14940: @kindex M-. @r{(V19)}
        !          14941: @kbd{M-.} (@code{find-tag}) and the other commands to find a tag now
        !          14942: look first for an exact match in the tags table, and try substring
        !          14943: matches only afterward.
        !          14944: 
        !          14945: Another change in @kbd{M-.} is that it has no effect on what @kbd{M-,}
        !          14946: will do subsequently.  You can no longer use @kbd{M-,} to find the next
        !          14947: similar tag; instead, use @kbd{M-.} with a prefix argument.
        !          14948: 
        !          14949: @findex find-tag-regexp @r{(V19)}
        !          14950: The new command @code{find-tag-regexp} successively visits the tags that
        !          14951: match a specified regular expression.
        !          14952: 
        !          14953: You can now use more than one tags table.  Using @code{visit-tags-table}
        !          14954: to load a new tags table does not discard the other tables previously
        !          14955: loaded.  The other tags commands use all the tags tables that are
        !          14956: loaded; the first one they use is the one that mentions the current
        !          14957: visited file.
        !          14958: 
        !          14959: You can specify a precise list of tags tables by setting the variable
        !          14960: @code{tags-table-list} to a list of strings, like this:
        !          14961: 
        !          14962: @c keep this on two lines for formatting in smallbook
        !          14963: @example
        !          14964: @group
        !          14965: (setq tags-table-list
        !          14966:       '("~/emacs" "/usr/local/lib/emacs/src"))
        !          14967: @end group
        !          14968: @end example
        !          14969: 
        !          14970: @noindent
        !          14971: This tells @code{find-tag} to look at the @file{TAGS} files in your
        !          14972: @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
        !          14973: directory.  The order depends on which file you are in and which tags
        !          14974: table mentions that file, as explained above.
        !          14975: 
        !          14976: @kindex M-@key{TAB} @r{(V19)}
        !          14977: You can now use the tags table for completion of names during ordinary
        !          14978: editing.  The command @kbd{M-@key{TAB}} (except in Emacs Lisp and Lisp
        !          14979: Interaction modes) completes the identifier in the buffer before point,
        !          14980: using the set of all tags as the list of possible completions.
        !          14981: 
        !          14982: @code{tags-query-replace} and @code{tags-search} now create buffers only
        !          14983: temporarily for the files that they have to search (those which are not
        !          14984: already visited in Emacs buffers).  If one of these files contains a
        !          14985: match for the search pattern, then its buffer continues to exist;
        !          14986: otherwise, it is killed.
        !          14987: 
        !          14988: @node Info Changes
        !          14989: @section Changes in Info
        !          14990: 
        !          14991: @cindex Info mode in V19
        !          14992: There are new commands in Info mode.
        !          14993: 
        !          14994: @c I don't think individual index entries for these commands
        !          14995: @c are useful.  I don't think anyone would ever look them up.--RMS.
        !          14996: @table @kbd
        !          14997: @item ]
        !          14998: Move forward a node, going up and down levels as needed in a depth-first
        !          14999: tree walk.  This command treats all the nodes in the file as forming a
        !          15000: single sequence in which the ``children'' of a node follow that node.
        !          15001: It is the equivalent of reading a printed manual sequentially.
        !          15002: 
        !          15003: @item [
        !          15004: Similar, but move backward.
        !          15005: 
        !          15006: @item <
        !          15007: Move to the top node of the current Info file.
        !          15008: 
        !          15009: @item >
        !          15010: Move to the last node of the file.
        !          15011: 
        !          15012: @c ??? Not done yet
        !          15013: @item @key{SPC}
        !          15014: Scroll through this node, or advance to the next node in depth-first
        !          15015: order (like @kbd{]}).
        !          15016: 
        !          15017: @c ??? Not done yet
        !          15018: @item i @var{string} @key{RET}
        !          15019: Move to the node associated with @var{string} in the index or indices of
        !          15020: this manual.  If there is more than one match for @var{string}, the
        !          15021: @kbd{i} command finds the first match.
        !          15022: 
        !          15023: @c ??? Not done yet
        !          15024: @item ,
        !          15025: Find the next match for the string in the previous @kbd{i} command, and
        !          15026: go to that node.
        !          15027: @end table
        !          15028: 
        !          15029: If you click the middle mouse button near a cross-reference,
        !          15030: menu item or node pointer while in Info, you will go to the node
        !          15031: which is referenced.
        !          15032: 
        !          15033: @vindex Info-directory-list @r{(V19)}
        !          15034: @vindex INFOPATH
        !          15035: The variable @code{Info-directory-list} specifies a list of directory
        !          15036: names that contain Info files.  Each time Info looks for an Info file,
        !          15037: it searches all these directories.  This makes it easy to install the
        !          15038: Info files that come with various packages.  You can specify the path
        !          15039: with the environment variable @code{INFOPATH}.
        !          15040: 
        !          15041: @node Dired Changes
        !          15042: @section Changes in Dired
        !          15043: 
        !          15044: @cindex Dired in V19
        !          15045: Dired has many new features which allow you to do these things:
        !          15046: 
        !          15047: @itemize @bullet
        !          15048: @item
        !          15049: Make distinguishable types of marks for different operations.
        !          15050: 
        !          15051: @item
        !          15052: Rename, copy, or make links to many files at once.
        !          15053: 
        !          15054: @item
        !          15055: Display contents of subdirectories in the same Dired buffer as the
        !          15056: parent directory.
        !          15057: @end itemize
        !          15058: 
        !          15059: @menu
        !          15060: * Marks in Dired::         Flagging for deletion vs marking for other actions.
        !          15061: * Multiple Files::         How to copy, rename, print, compress, etc.
        !          15062:                              either one file or several files.
        !          15063: * Shell Commands in Dired:: Running a shell command on the marked files.
        !          15064: * Dired Regexps::          Using patterns to rename multiple files.
        !          15065: * Dired Case Conversion::   Converting file names to upper or lower case.
        !          15066: * Comparison in Dired::            Running `diff' by way of Dired.
        !          15067: * Subdirectories in Dired:: Adding subdirectories to the Dired buffer.
        !          15068: * Hiding Subdirectories::   Making subdirectories visible or invisible.
        !          15069: * Editing Dired Buffer::    Discarding lines for files of no interest.
        !          15070: * Dired and Find::         Using `find' to select the files for Dired to show.
        !          15071: @end menu
        !          15072: 
        !          15073: @node Marks in Dired
        !          15074: @subsection Setting and Clearing Marks
        !          15075: 
        !          15076: @cindex Marks in Dired (V19)
        !          15077: There are now two kinds of marker that you can put on a file in Dired:
        !          15078: @samp{D} for deletion, and @samp{*} for any other kind of operation.
        !          15079: The @kbd{x} command deletes only files marked with @samp{D}, and most
        !          15080: other Dired commands operate only on the files marked with @samp{*}.
        !          15081: 
        !          15082: To mark files with @samp{D} (also called @dfn{flagging} the files), you
        !          15083: can use @kbd{d} as usual.  Here are some commands for marking with
        !          15084: @samp{*} (and also for unmarking):
        !          15085: 
        !          15086: @table @kbd
        !          15087: @kindex m @r{(Dired, V19)}
        !          15088: @findex dired-mark @r{(V19)}
        !          15089: @item m
        !          15090: Mark the current file with @samp{*}, for an
        !          15091: operation other than deletion (@code{dired-mark}).
        !          15092: 
        !          15093: @kindex * @r{(Dired, V19)}
        !          15094: @findex dired-mark-executables @r{(V19)}
        !          15095: @item *
        !          15096: Mark all executable files (@code{dired-mark-executables}).
        !          15097: With a prefix argument, unmark all those files.
        !          15098: 
        !          15099: @item @@
        !          15100: @kindex @@ @r{(Dired, V19)}
        !          15101: @findex dired-mark-symlinks @r{(V19)}
        !          15102: Mark all symbolic links (@code{dired-mark-symlinks}).  With a
        !          15103: prefix argument, unmark all those files.
        !          15104: 
        !          15105: @item /
        !          15106: @kindex / @r{(Dired, V19)}
        !          15107: @findex dired-mark-directories @r{(V19)}
        !          15108: Mark all files which are actually directories, except for @file{.} and
        !          15109: @file{..} (@code{dired-mark-directories}).  With a prefix argument,
        !          15110: unmark all those files.
        !          15111: 
        !          15112: @item M-@key{DEL}
        !          15113: @kindex M-@key{DEL} @r{(Dired, V19)}
        !          15114: @findex dired-unmark-all-files @r{(V19)}
        !          15115: Remove a specific or
        !          15116: all marks from every file (@code{dired-unmark-all-files}).  
        !          15117: With an argument, query for each marked file.  
        !          15118: Type your help character, usually @kbd{C-h}, at that time for help.
        !          15119: 
        !          15120: @item c @var{old} @var{new}
        !          15121: @kindex c @r{(Dired, V19)}
        !          15122: @findex dired-change-marks @r{(V19)}
        !          15123: Replace all marks that use the character @var{old} with marks that use
        !          15124: the character @var{new}.  You can use almost any character as a mark
        !          15125: character by means of this command, to distinguish various classes of
        !          15126: files.  If @var{old} is @samp{ }, then the command operates on all
        !          15127: unmarked files; if @var{new} is @samp{ }, then the command unmarks the
        !          15128: files it acts on.
        !          15129: 
        !          15130: To illustrate the power of this command, here is how to put @samp{*}
        !          15131: marks on all the files that were unmarked, while unmarking all those
        !          15132: that had @samp{*} marks:
        !          15133: 
        !          15134: @example
        !          15135: c * t c SPC * c t SPC
        !          15136: @end example
        !          15137: @end table
        !          15138: 
        !          15139: @node Multiple Files
        !          15140: @subsection Operating on Multiple Files
        !          15141: 
        !          15142: @cindex Multiple file ops, Dired (V19)
        !          15143: @cindex Dired multiple file ops (V19)
        !          15144: The Dired commands to operate on files (rename them, copy them, and so
        !          15145: on) have been generalized to work on multiple files.  There are also
        !          15146: some additional commands in this series.
        !          15147: 
        !          15148: All of these commands use the same convention to decide which files to
        !          15149: manipulate:
        !          15150: 
        !          15151: @itemize @bullet
        !          15152: @item
        !          15153: If you give the command a numeric prefix argument @var{n}, it operates
        !          15154: on the next @var{n} files, starting with the current file.
        !          15155: 
        !          15156: @item
        !          15157: Otherwise, if there are marked files, the commands operate on all the
        !          15158: marked files.
        !          15159: 
        !          15160: @item
        !          15161: Otherwise, the command operates on the current file only.
        !          15162: @end itemize
        !          15163: 
        !          15164: Here are the commands that operate on multiple files in this way:
        !          15165: 
        !          15166: @table @kbd
        !          15167: @findex dired-do-copy @r{(V19)}
        !          15168: @kindex C @r{(Dired, V19)}
        !          15169: @item C
        !          15170: Copy the specified files (@code{dired-do-copy}).  You must
        !          15171: specify a directory to copy into, or (if copying a single file) a new
        !          15172: name.
        !          15173: 
        !          15174: @vindex dired-copy-preserve-time @r{(V19)}
        !          15175: If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with
        !          15176: this command sets the modification time of the new file to be the same
        !          15177: as that of the old file.
        !          15178: 
        !          15179: @findex dired-do-rename @r{(V19)}
        !          15180: @kindex R @r{(Dired, V19)}
        !          15181: @item R 
        !          15182: Rename the specified files (@code{dired-do-rename}).  You must
        !          15183: specify a directory to rename into, or (if renaming a single file) a new
        !          15184: name.
        !          15185: 
        !          15186: Dired automatically changes the visited file name of buffers associated
        !          15187: with renamed files so that they refer to the new names.
        !          15188: 
        !          15189: @findex dired-do-hardlink @r{(V19)}
        !          15190: @kindex H @r{(Dired, V19)}
        !          15191: @item H
        !          15192: Make hard links to the specified
        !          15193: files (@code{dired-do-hardlink}).  
        !          15194: You must specify a directory to make the links in, or (if making
        !          15195: just one link) the name to give the link.
        !          15196: 
        !          15197: @findex dired-do-symlink @r{(V19)}
        !          15198: @kindex S @r{(Dired, V19)}
        !          15199: @item S
        !          15200: Make symbolic links to the specified
        !          15201: files (@code{dired-do-symlink}).  
        !          15202: You must specify a directory to make the links in, or (if making
        !          15203: just one link) the name to give the link.
        !          15204: 
        !          15205: @findex dired-do-chmod @r{(V19)}
        !          15206: @kindex M @r{(Dired, V19)}
        !          15207: @item M
        !          15208: Change the mode (also called ``permission bits'') 
        !          15209: of the specified files (@code{dired-do-chmod}).  This calls the
        !          15210: @code{chmod} program, so you can describe the desired mode change with
        !          15211: any argument that @code{chmod} would handle.
        !          15212: 
        !          15213: @findex dired-do-chgrp @r{(V19)}
        !          15214: @kindex G @r{(Dired, V19)}
        !          15215: @item G
        !          15216: Change the group of the specified files (@code{dired-do-chgrp}).
        !          15217: 
        !          15218: @vindex dired-chown-program @r{(V19)}
        !          15219: @findex dired-do-chown @r{(V19)}
        !          15220: @kindex O @r{(Dired, V19)}
        !          15221: @item O
        !          15222: Change the owner of the specified
        !          15223: files (@code{dired-do-chown}).  
        !          15224: (On most systems, only the superuser can do this.)
        !          15225: 
        !          15226: The variable @code{dired-chown-program} specifies the name of the
        !          15227: program to use to do the work (different systems put @code{chown} in
        !          15228: different places.
        !          15229: 
        !          15230: @findex dired-do-compress @r{(V19)}
        !          15231: @kindex Z @r{(Dired, V19)}
        !          15232: @item Z
        !          15233: @c !!! Rewrote to prevent overfull hbox.
        !          15234: Compress or uncompress the specified files.
        !          15235: If the file appears to be a compressed file, it is uncompressed;
        !          15236: otherwise, it is compressed (@code{dired-do-compress}).
        !          15237: 
        !          15238: @findex dired-do-load @r{(V19)}
        !          15239: @kindex L @r{(Dired, V19)}
        !          15240: @item L
        !          15241: Load the specified Emacs Lisp files (@code{dired-do-load}).
        !          15242: 
        !          15243: @findex dired-do-byte-compile @r{(V19)}
        !          15244: @kindex B @r{(Dired, V19)}
        !          15245: @item B
        !          15246: Byte compile the specified Emacs Lisp files
        !          15247: (@code{dired-do-byte-compile}).
        !          15248: 
        !          15249: @findex dired-do-print @r{(V19)}
        !          15250: @kindex P @r{(Dired, V19)}
        !          15251: @item P
        !          15252: Print the specified files (@code{dired-do-print}).  This command uses
        !          15253: the variables @code{lpr-command} and @code{lpr-switches} just as
        !          15254: @code{lpr-file} does (@pxref{Hardcopy}).
        !          15255: @end table
        !          15256: 
        !          15257: @node Shell Commands in Dired
        !          15258: @subsection Shell Commands in Dired
        !          15259: @cindex shell commands, Dired V19
        !          15260: 
        !          15261: @findex dired-do-shell-command @r{(V19)}
        !          15262: @kindex ! @r{(Dired, V19)}
        !          15263: The dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell
        !          15264: command string in the minibuffer and runs the shell command on all the
        !          15265: specified files.  There are two ways of applying a shell command to
        !          15266: multiple files:
        !          15267: 
        !          15268: @itemize @bullet
        !          15269: @item
        !          15270: If you use @samp{*} in the shell command, then it runs just once, with
        !          15271: the list of file names substituted for the @samp{*}.
        !          15272: 
        !          15273: Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire
        !          15274: list of file names, putting them into one tar file @file{foo.tar}.  The
        !          15275: file names are inserted in the order that they appear in the Dired
        !          15276: buffer.
        !          15277: 
        !          15278: @item
        !          15279: If the command string doesn't contain @samp{*}, then it runs once
        !          15280: @emph{for each file}, with the file name attached at the end.
        !          15281: 
        !          15282: For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each
        !          15283: file.
        !          15284: @end itemize
        !          15285: 
        !          15286: What if you want to run the shell command once for each file but with
        !          15287: the file name inserted in the middle?  Or if you want to use the file
        !          15288: names in a more complicated fashion?  Use a shell loop.  For example,
        !          15289: this shell command would run @code{uuencode} on each of the specified
        !          15290: files, writing the output into a corresponding @file{.uu} file:
        !          15291: 
        !          15292: @example
        !          15293: for file in *; uuencode $file $file >$file.uu; done
        !          15294: @end example
        !          15295: 
        !          15296: The working directory for the shell command is the top level directory
        !          15297: of the Dired buffer.
        !          15298: 
        !          15299: The @kbd{!} command does not attempt to update the Dired buffer to show
        !          15300: new or modified files, because it doesn't know what those files might
        !          15301: be.  Type @kbd{g} to update the Dired buffer.
        !          15302: 
        !          15303: @node Dired Regexps
        !          15304: @subsection Regular Expression File Name Substitution
        !          15305: 
        !          15306: Here are commands that select files according to a regular
        !          15307: expression:
        !          15308: 
        !          15309: @table @kbd
        !          15310: @findex dired-mark-files-regexp @r{(V19)}
        !          15311: @kindex % m @r{(Dired, V19)}
        !          15312: @item % m @var{regexp} @key{RET}
        !          15313: Mark all files whose names match the regular expression @var{regexp}
        !          15314: (@code{dired-mark-files-regexp}).
        !          15315: 
        !          15316: Only the non-directory part of the file name is used in matching.  Use
        !          15317: @samp{^} and @samp{$} to anchor matches.  Exclude subdirs by hiding
        !          15318: them (@pxref{Hiding Subdirectories}).
        !          15319: 
        !          15320: @item % d @var{regexp} @key{RET}
        !          15321: @findex dired-flag-files-regexp @r{(V19)}
        !          15322: @kindex % d @r{(Dired, V19)}
        !          15323: Flag for deletion all files whose names match the regular expression
        !          15324: @var{regexp} (@code{dired-flag-files-regexp}).
        !          15325: 
        !          15326: @item % R @var{from} @key{RET} @var{to} @key{RET}
        !          15327: @kindex % R @r{(Dired, V19)}
        !          15328: @findex dired-do-rename-regexp @r{(V19)}
        !          15329: @itemx % C @var{from} @key{RET} @var{to} @key{RET}
        !          15330: @kindex % C @r{(Dired, V19)}
        !          15331: @findex dired-do-copy-regexp @r{(V19)}
        !          15332: @itemx % H @var{from} @key{RET} @var{to} @key{RET}
        !          15333: @kindex % H @r{(Dired, V19)}
        !          15334: @findex dired-do-hardlink-regexp @r{(V19)}
        !          15335: @itemx % S @var{from} @key{RET} @var{to} @key{RET}
        !          15336: @kindex % S @r{(Dired, V19)}
        !          15337: @findex dired-do-symlink-regexp @r{(V19)}
        !          15338: These four commands rename, copy, make hard links and make soft links,
        !          15339: in each case computing the new name by regular expression substitution
        !          15340: from the name of the old file.
        !          15341: @end table
        !          15342: 
        !          15343: The four regular expression substitution commands effectively perform
        !          15344: @code{query-replace-regexp} on the selected file names in the Dired
        !          15345: buffer.  They read two arguments: a regular expression @var{from}, and a
        !          15346: substitution pattern @var{to}.  Each selected file name is matched
        !          15347: against the regular expression, and then the part which matched is
        !          15348: replaced with the substitution pattern.  You can use @samp{\&} and
        !          15349: @samp{\@var{digit}} in the substitution pattern to refer to all or part
        !          15350: of the old file name.
        !          15351: @c ??? xref{???query replace???}.
        !          15352: 
        !          15353: Thus, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each selected file
        !          15354: by prepending @samp{x-} to its name.  The inverse of this is to remove
        !          15355: @samp{x-} from the front of each file name.  One way to do that is
        !          15356: @kbd{% R ^x-.*$ @key{RET} \& @key{RET}}; another is @w{@kbd{% R ^x-
        !          15357: @key{RET} @key{RET}}}.  (Use @samp{^} and @samp{$} to anchor matches that
        !          15358: should span the whole filename.)
        !          15359: 
        !          15360: If the regular expression matches more than once in a file name,
        !          15361: only the first match is replaced.
        !          15362: 
        !          15363: Normally, the replacement process does not consider the directory names;
        !          15364: it operates on the file name within the directory.  If you specify a
        !          15365: prefix argument of zero, then replacement affects the entire file name.
        !          15366: 
        !          15367: Often you will want to apply the command to all files matching the same
        !          15368: @var{regexp} that you use in the command.  To do this, mark those files
        !          15369: with @w{@kbd{% m @var{regexp} @key{RET}}}, then use the same regular
        !          15370: expression in @kbd{% R}.  To make this easier, @kbd{% R} uses the
        !          15371: last regular expression specified in a @kbd{%} command as a default.
        !          15372: 
        !          15373: @node Dired Case Conversion
        !          15374: @subsection Dired Case Conversion
        !          15375: @cindex case conversion of file names @r{(V19)}
        !          15376: 
        !          15377: Here are commands for changing the case of selected files:
        !          15378: 
        !          15379: @table @code
        !          15380: @findex dired-upcase @r{(V19)}
        !          15381: @kindex % u @r{(Dired, V19)}
        !          15382: @item % u
        !          15383: Rename each of the selected files to an
        !          15384: upper case name (@code{dired-upcase}).
        !          15385: 
        !          15386: @item % l
        !          15387: @findex dired-downcase @r{(V19)}
        !          15388: @kindex % l @r{(Dired, V19)}
        !          15389: Rename each of the selected files to
        !          15390: a lower case name (@code{dired-downcase}).
        !          15391: @end table
        !          15392: 
        !          15393: @node Comparison in Dired
        !          15394: @subsection File Comparison with Dired
        !          15395: 
        !          15396: Here are two commands to run @code{diff} on selected files:
        !          15397: 
        !          15398: @table @kbd
        !          15399: @findex dired-diff @r{(V19)}
        !          15400: @kindex = @r{(Dired, V19)}
        !          15401: @item =
        !          15402: Compare the current file with another file (the file at the mark), by
        !          15403: running the @code{diff} program (@code{dired-diff}).  The file at the
        !          15404: mark is the first argument of @code{diff}, and the file at point is the
        !          15405: second argument.
        !          15406: 
        !          15407: @findex dired-backup-diff @r{(V19)}
        !          15408: @kindex M-= @r{(Dired, V19)}
        !          15409: @item M-=
        !          15410: Compare the current file with its
        !          15411: backup file (@code{dired-backup-diff}).  
        !          15412: If there are several numerical backups, use the most
        !          15413: recent one.  If this file is a backup, compare it to its
        !          15414: original.  The backup file is the first file given to @code{diff}.
        !          15415: @end table
        !          15416: 
        !          15417: @node Subdirectories in Dired
        !          15418: @subsection Subdirectories in Dired
        !          15419: @cindex subdirectories in Dired (V19)
        !          15420: @cindex expanding subdirectories in Dired  (V19)
        !          15421: 
        !          15422: One Dired buffer can now display more than one directory.
        !          15423: 
        !          15424: The simplest way to include multiple directories is to specify the
        !          15425: options @samp{-lR} for running @code{ls}.  That produces a recursive
        !          15426: directory listing showing all subdirectories, all within the same Dired
        !          15427: buffer.
        !          15428: 
        !          15429: But the simplest way is not usually the most convenient way---usually
        !          15430: the complete recursive listing is more than you want.  So there is a
        !          15431: Dired command to insert a single subdirectory into the Dired buffer:
        !          15432: 
        !          15433: @table @kbd
        !          15434: @findex dired-maybe-insert-subdir @r{(V19)}
        !          15435: @kindex i @r{(Dired, V19)}
        !          15436: @item i
        !          15437: @cindex inserted subdirectory (Dired, V19)
        !          15438: @cindex expanded subdirectory (Dired, V19)
        !          15439: @cindex in-situ subdirectory (Dired, V19)
        !          15440: @cindex headerline (Dired, V19)
        !          15441: Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line
        !          15442: that describes a file which is a directory.  It inserts the contents of
        !          15443: that directory into the same Dired buffer.  Inserted subdirectory
        !          15444: contents follow the top-level directory of the Dired buffer, just as
        !          15445: they do in @samp{ls -lR} output.
        !          15446: 
        !          15447: If the subdirectory's contents are already present in the buffer, the
        !          15448: @kbd{i} command just moves to it (type @kbd{l}
        !          15449: (@code{dired-do-redisplay}) to refresh it).  It sets the Emacs mark
        !          15450: before moving, so @kbd{C-x C-x} takes you back to the old position in
        !          15451: the buffer.
        !          15452: @end table
        !          15453: 
        !          15454: When you have subdirectories in the Dired buffer, you can use the page
        !          15455: motion commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories.
        !          15456: 
        !          15457: The following commands move up and down in the tree of directories
        !          15458: in one Dired buffer:
        !          15459: 
        !          15460: @table @kbd
        !          15461: @findex dired-tree-up @r{(V19)}
        !          15462: @kindex C-M-u @r{(Dired, V19)}
        !          15463: @item C-M-u
        !          15464: Go up to the parent directory's headerline (@code{dired-tree-up}).
        !          15465: 
        !          15466: @findex dired-tree-down @r{(V19)}
        !          15467: @kindex C-M-d @r{(Dired, V19)}
        !          15468: @item C-M-d
        !          15469: Go down in the tree, to the first
        !          15470: subdirectory's headerline (@code{dired-tree-down}).
        !          15471: @end table
        !          15472: 
        !          15473: The following commands move forwards and backwards to subdirectory headerlines:
        !          15474: 
        !          15475: @table @kbd
        !          15476: @findex dired-next-subdir @r{(V19)}
        !          15477: @kindex C-M-n @r{(Dired, V19)}
        !          15478: @item C-M-n
        !          15479: Go to next subdirectory headerline,
        !          15480: regardless of level (@code{dired-next-subdir}).
        !          15481: 
        !          15482: @findex dired-prev-subdir @r{(V19)}
        !          15483: @kindex C-M-p @r{(Dired, V19)}
        !          15484: @item C-M-p
        !          15485: @c !!! added @* to prevent overfull hbox
        !          15486: Go to previous subdirectory headerline,
        !          15487: regardless of level@*
        !          15488: (@code{dired-prev-subdir}).
        !          15489: @end table
        !          15490: 
        !          15491: @node Hiding Subdirectories
        !          15492: @subsection Hiding Subdirectories
        !          15493: 
        !          15494: @cindex hiding in Dired (Dired, V19)
        !          15495: @dfn{Hiding} a subdirectory means to make it invisible, except for its
        !          15496: headerline.  Files inside a hidden subdirectory are never considered by
        !          15497: Dired.  For example, the commands to operate on marked files ignore
        !          15498: files in hidden directories even if they are marked.  Thus you can use
        !          15499: hiding to temporarily exclude subdirectories from operations without
        !          15500: having to remove the markers.
        !          15501: 
        !          15502: The hiding commands toggle; that is they unhide what was hidden and vice
        !          15503: versa.
        !          15504: 
        !          15505: @table @kbd
        !          15506: @item $
        !          15507: @findex dired-hide-subdir @r{(V19)}
        !          15508: @kindex $ @r{(Dired, V19)}
        !          15509: Hide or reveal the current subdirectory and move point to the next
        !          15510: subdirectory (@code{dired-hide-subdir}).  A prefix argument serves as
        !          15511: a repeat count.
        !          15512: 
        !          15513: @item M-$
        !          15514: @findex dired-hide-all @r{(V19)}
        !          15515: @kindex M-$ @r{(Dired, V19)}
        !          15516: Hide all subdirectories, leaving only their header lines
        !          15517: (@code{dired-hide-all}).  Or, if any subdirectory is currently hidden,
        !          15518: make all subdirectories visible again.  You can use this command to get
        !          15519: an overview in very deep directory trees or to move quickly to
        !          15520: subdirectories far away.
        !          15521: @end table
        !          15522: 
        !          15523: @node Editing Dired Buffer
        !          15524: @subsection Editing the Dired Buffer
        !          15525: 
        !          15526: @table @kbd
        !          15527: @kindex l @r{(Dired, V19)}
        !          15528: @findex dired-do-redisplay @r{(V19)}
        !          15529: @item l
        !          15530: @c !!! rewrote to prevent overfull hbox
        !          15531: Update the specified files in a Dired buffer.  This means reading their
        !          15532: current status from the file system and changing the buffer to reflect
        !          15533: it properly (@code{dired-do-redisplay}).
        !          15534: 
        !          15535: If you use this command on a subdirectory header line, it updates the
        !          15536: contents of the subdirectory.
        !          15537: 
        !          15538: @kindex g @r{(Dired, V19)}
        !          15539: @findex revert-buffer @r{(Dired, V19)}
        !          15540: @item g
        !          15541: Update the entire contents of the Dired buffer
        !          15542: (@code{revert-buffer}).  Preserve all marks except for those on files
        !          15543: that have vanished.  Hidden subdirectories are updated but remain
        !          15544: hidden.
        !          15545: 
        !          15546: @kindex k @r{(Dired, V19)}
        !          15547: @findex dired-do-kill-lines @r{(V19)}
        !          15548: @item k
        !          15549: Kill all marked lines (@code{dired-do-kill-lines}).  With a prefix
        !          15550: argument, kill that many lines starting with the current line.
        !          15551: 
        !          15552: This command does not delete files; it just deletes text from the Dired
        !          15553: buffer.
        !          15554: 
        !          15555: If you kill the line for a file that is a directory, then its contents
        !          15556: are also deleted from the buffer.  Typing @kbd{C-u k} on the header line
        !          15557: for a subdirectory is another way to delete a subdirectory from the
        !          15558: Dired buffer.
        !          15559: 
        !          15560: The @kbd{g} command will bring back any individual lines that you have
        !          15561: killed in this way, but not subdirectories---you must use @kbd{i} to
        !          15562: reinsert each subdirectory.
        !          15563: @end table
        !          15564: 
        !          15565: @node Dired and Find
        !          15566: @subsection Dired and @code{find}
        !          15567: @cindex @code{find} and Dired
        !          15568: 
        !          15569:   You can select a set of files for display in a Dired buffer more
        !          15570: flexibly by using the @code{find} utility to choose the files.
        !          15571: 
        !          15572: @findex find-name-dired
        !          15573: To search for files with names matching a wildcard pattern use
        !          15574: @code{find-name-dired}.  Its arguments are @var{directory} and
        !          15575: @var{pattern}.  It selects all the files in @var{directory} or its
        !          15576: subdirectories whose own names match @var{pattern}.
        !          15577: 
        !          15578: The files thus selected are displayed in a Dired buffer in which the
        !          15579: ordinary Dired commands are available.
        !          15580: 
        !          15581: @findex find-grep-dired
        !          15582: If you want to test the contents of files, rather than their names, use
        !          15583: @code{find-grep-dired}.  This command takes two minibuffer arguments,
        !          15584: @var{directory} and @var{regexp}; it selects all the files in
        !          15585: @var{directory} or its subdirectories that contain a match for
        !          15586: @var{regexp}.  It works by running @code{find} and @code{grep}.
        !          15587: 
        !          15588: @findex find-dired
        !          15589: The most general command in this series is @code{find-dired}, which lets
        !          15590: you specify any condition that @code{find} can test.  It takes two
        !          15591: minibuffer arguments, @var{directory} and @var{find-args}; it runs
        !          15592: @code{find} in @var{directory} with @var{find-args} as the
        !          15593: arguments to @code{find} that specify which files to accept.  To use this
        !          15594: command, you need to know how to use @code{find}.
        !          15595: 
        !          15596: @node GNUS
        !          15597: @section GNUS
        !          15598: @cindex @sc{gnus}
        !          15599: @cindex reading netnews
        !          15600: 
        !          15601: @sc{gnus} is an Emacs subsystem for reading and responding to netnews.  You
        !          15602: can use @sc{gnus} to browse through news groups, look at summaries of
        !          15603: articles in specific group, and read articles of interest.  You can
        !          15604: respond to authors or write replies to all the readers of a news group.
        !          15605: 
        !          15606: This document introduces @sc{gnus} and describes several basic features.
        !          15607: Full documentation will appear in @cite{The GNU Emacs Extensions Manual}.
        !          15608: 
        !          15609: @kindex M-x gnus @r{(V19)}
        !          15610: @findex gnus @r{(V19)}
        !          15611: To start @sc{gnus}, type @kbd{M-x gnus @key{RET}}.
        !          15612: 
        !          15613: @menu
        !          15614: * Buffers of GNUS::   The Newsgroups, Summary and Article buffers.
        !          15615: * GNUS Startup::      What you should know about starting GNUS.
        !          15616: * Summary of GNUS::   A short description of the basic GNUS commands.
        !          15617: @end menu
        !          15618: 
        !          15619: @node Buffers of GNUS
        !          15620: @subsection @sc{GNUS}'s Three Buffers
        !          15621: 
        !          15622: @sc{gnus} creates and uses three Emacs buffers, each with its own
        !          15623: particular purpose and its own major mode.
        !          15624: 
        !          15625: The @dfn{Newsgroup buffer} contains a list of newsgroups.  This is the
        !          15626: first buffer that @sc{gnus} displays when it starts up.  Normally the list
        !          15627: contains only the newsgroups to which you subscribe (which are listed in
        !          15628: your @file{.newsrc} file) and which contain unread articles.  Use this
        !          15629: buffer to select a specific newsgroup.
        !          15630: 
        !          15631: The @dfn{Summary buffer} lists the articles in a single newsgroup,
        !          15632: including their subjects, their numbers, and who posted them.  @sc{gnus}
        !          15633: creates a Summary buffer for a newsgroup when you select the group in
        !          15634: the Newsgroup buffer.  Use this buffer to select an article, and to move
        !          15635: around in an article.
        !          15636: 
        !          15637: The @dfn{Article buffer} displays the text of an article.  You rarely
        !          15638: need to select this buffer because you can read the text while keeping
        !          15639: the Summary buffer selected.
        !          15640: 
        !          15641: @node GNUS Startup
        !          15642: @subsection When @sc{GNUS} Starts Up
        !          15643: 
        !          15644: At startup, @sc{gnus} reads your @file{.newsrc} news initialization file
        !          15645: and attempts to communicate with the local news server, which is a
        !          15646: repository of news articles.  The news server need not be the same
        !          15647: computer you are logged in on.
        !          15648: 
        !          15649: If you start @sc{gnus} and connect to the server, but do not see any
        !          15650: newsgroups listed in the Newsgroup buffer, type @kbd{L} to get a listing
        !          15651: of all the newsgroups.  Then type @kbd{u} to unsubscribe from particular
        !          15652: newsgroups.  (Move the cursor using @kbd{n} and @kbd{p} or the usual
        !          15653: Emacs commands.)  When you quit with @kbd{q}, @sc{gnus} automatically
        !          15654: records the subscribed groups in your @file{.newsrc} initialization
        !          15655: file.  (You do not have to edit this file yourself, although you may.)
        !          15656: Next time you start @sc{gnus}, you will see only the subscribed groups.
        !          15657: 
        !          15658: @node Summary of GNUS
        !          15659: @subsection Summary of GNUS Commands
        !          15660: 
        !          15661: Reading news is a two step process:
        !          15662: 
        !          15663: @enumerate
        !          15664: @item
        !          15665: Choose a newsgroup in the Newsgroup buffer.
        !          15666: 
        !          15667: @item
        !          15668: Choose an article in the Summary buffer.  The article is displayed in
        !          15669: the Article buffer in a large window, below the Summary buffer in its
        !          15670: small window.
        !          15671: @end enumerate
        !          15672: 
        !          15673: Each buffer has commands particular to it, but commands that do the same
        !          15674: things have similar keybindings.  Here are commands for the Newsgroup
        !          15675: and Summary buffers:
        !          15676: 
        !          15677: @table @kbd
        !          15678: @kindex z @r{(Group mode)} @r{(GNUS, V19)}
        !          15679: @findex gnus-Group-suspend @r{(V19)}
        !          15680: @item z
        !          15681: In the Newsgroup buffer, suspend @sc{gnus}.  You can return to @sc{gnus} later by
        !          15682: selecting the Newsgroup buffer and typing @kbd{g} to get newly arrived
        !          15683: articles.
        !          15684: 
        !          15685: @kindex q @r{(Group mode)} @r{(GNUS, V19)}
        !          15686: @findex gnus-Group-exit @r{(V19)}
        !          15687: @item q
        !          15688: In the Newsgroup buffer, update your @file{.newsrc} initialization file
        !          15689: and quit @sc{gnus}.
        !          15690: 
        !          15691: In the Summary buffer, exit the current newsgroup and return to the
        !          15692: Newsgroup buffer.  Thus, typing @kbd{q} twice quits @sc{gnus}.
        !          15693: 
        !          15694: @kindex L @r{(Group mode)} @r{(GNUS, V19)}
        !          15695: @findex gnus-Group-list-all-groups @r{(V19)}
        !          15696: @item L
        !          15697: In the Newsgroup buffer, list all the newsgroups available on your news
        !          15698: server.  This may be a long list!
        !          15699: 
        !          15700: @kindex l @r{(Group mode)} @r{(GNUS, V19)}
        !          15701: @findex gnus-Group-list-groups @r{(V19)}
        !          15702: @item l
        !          15703: In the Newsgroup buffer, list only the newsgroups to which you subscribe
        !          15704: and which contain unread articles.
        !          15705: 
        !          15706: @kindex u @r{(Group mode)} @r{(GNUS, V19)}
        !          15707: @findex gnus-Group-unsubscribe-current-group @r{(V19)}
        !          15708: @cindex subscribe newsgroups (V19)
        !          15709: @cindex unsubscribe newsgroups (V19)
        !          15710: @item u
        !          15711: In the Newsgroup buffer, unsubscribe from (or subscribe to) the
        !          15712: newsgroup listed in the line that point is on.  When you quit @sc{gnus} by
        !          15713: typing @kbd{q}, @sc{gnus} lists your subscribed-to newsgroups in your
        !          15714: @file{.newsrc} file.  The next time you start @sc{gnus}, you see only the
        !          15715: newsgroups listed in your @file{.newsrc} file.
        !          15716: 
        !          15717: You may also edit your @file{.newsrc} file directly in Emacs.  First quit
        !          15718: @sc{gnus}, then visit the @file{.newsrc} file.  For example, you can remove
        !          15719: all the @file{alt.} groups by going to the beginning of the file and
        !          15720: typing @kbd{M-x flush-lines RET alt RET}.  Next time you start @sc{gnus}, you
        !          15721: will see only the newsgroups still listed in the @file{.newsrc} file.
        !          15722: 
        !          15723: @kindex SPC @r{(Group mode)} @r{(GNUS, V19)}
        !          15724: @findex gnus-Group-read-group @r{(V19)}
        !          15725: @item @key{SPC}
        !          15726: In the Newsgroup buffer, select the group on the line under the cursor
        !          15727: and display the first unread article in that group.
        !          15728: 
        !          15729: @kindex SPC @r{(Summary mode)} @r{(GNUS, V19)}
        !          15730: @findex gnus-Summary-next-page @r{(V19)}
        !          15731: @need 1000
        !          15732: In the Summary buffer, 
        !          15733: 
        !          15734: @itemize @minus
        !          15735: @item
        !          15736: Select the article on the line under the cursor if none is selected.
        !          15737: 
        !          15738: @item
        !          15739: Scroll the text of the article if one is selected.
        !          15740: 
        !          15741: @item
        !          15742: Select the next unread article if at the end of the current article.
        !          15743: @end itemize
        !          15744: 
        !          15745: Thus, you can move through all the articles by repeatedly typing @key{SPC}.
        !          15746: 
        !          15747: @kindex DEL @r{(Group mode)} @r{(GNUS, V19)}
        !          15748: @item @key{DEL}
        !          15749: In the Newsgroup Buffer, move point to the previous newsgroup containing
        !          15750: unread articles.
        !          15751: 
        !          15752: @kindex DEL @r{(Summary mode)} @r{(GNUS, V19)}
        !          15753: @findex gnus-Summary-prev-page @r{(V19)}
        !          15754: In the Summary buffer, scroll the text of the article backwards.
        !          15755: 
        !          15756: @kindex n @r{(Group mode)} @r{(GNUS, V19)}
        !          15757: @findex gnus-Group-next-unread-group @r{(V19)}
        !          15758: @item n
        !          15759: Move point to the next unread newsgroup, or select the next unread
        !          15760: article.
        !          15761: 
        !          15762: @kindex p @r{(Group mode)} @r{(GNUS, V19)}
        !          15763: @findex gnus-Group-prev-unread-group @r{(V19)}
        !          15764: @item p
        !          15765: Move point to the previous unread newsgroup, or select the previous
        !          15766: unread article.
        !          15767: 
        !          15768: @kindex C-n @r{(Group mode)} @r{(GNUS, V19)}
        !          15769: @findex gnus-Group-next-group @r{(V19)}
        !          15770: @kindex C-p @r{(Group mode)} @r{(GNUS, V19)}
        !          15771: @findex gnus-Group-prev-group @r{(V19)}
        !          15772: @kindex C-n @r{(Summary mode)} @r{(GNUS, V19)}
        !          15773: @findex gnus-Summary-next-subject @r{(V19)}
        !          15774: @kindex C-p @r{(Summary mode)} @r{(GNUS, V19)}
        !          15775: @findex gnus-Summary-prev-subject @r{(V19)}
        !          15776: @itemx C-n
        !          15777: @itemx C-p
        !          15778: Move point to the next or previous item, even if it is marked as read.
        !          15779: This does not select the article or newsgroup on that line.
        !          15780: 
        !          15781: @kindex s @r{(Summary mode)} @r{(GNUS, V19)}
        !          15782: @findex gnus-Summary-isearch-article @r{(V19)}
        !          15783: @item s
        !          15784: In the Summary buffer, do an incremental search of the current text in
        !          15785: the Article buffer, just as if you switched to the Article buffer and
        !          15786: typed @kbd{C-s}.
        !          15787: 
        !          15788: @kindex M-s @r{(Summary mode)} @r{(GNUS, V19)}
        !          15789: @findex gnus-Summary-search-article-forward @r{(V19)}
        !          15790: @item M-s @var{regexp} RET
        !          15791: In the Summary buffer, search forward for articles containing a match
        !          15792: for @var{regexp}.
        !          15793: 
        !          15794: @c kindex C-c C-s C-n @r{(Summary mode)} @r{(GNUS, V19)}
        !          15795: @findex gnus-Summary-sort-by-number @r{(V19)}
        !          15796: @c kindex C-c C-s C-s @r{(Summary mode)} @r{(GNUS, V19)}
        !          15797: @findex gnus-Summary-sort-by-subject @r{(V19)}
        !          15798: @c kindex C-c C-s C-d @r{(Summary mode)} @r{(GNUS, V19)}
        !          15799: @findex gnus-Summary-sort-by-date @r{(V19)}
        !          15800: @c kindex C-c C-s C-a @r{(Summary mode)} @r{(GNUS, V19)}
        !          15801: @findex gnus-Summary-sort-by-author @r{(V19)}
        !          15802: @item C-c C-s C-n
        !          15803: @itemx C-c C-s C-s
        !          15804: @itemx C-c C-s C-d
        !          15805: @itemx C-c C-s C-a
        !          15806: In the Summary buffer, sort the list of articles by number, subject,
        !          15807: date, or author.
        !          15808: 
        !          15809: @kindex C-M-n @r{(Summary mode)} @r{(GNUS, V19)}
        !          15810: @findex gnus-Summary-next-same-subject @r{(V19)}
        !          15811: @kindex C-M-p @r{(Summary mode)} @r{(GNUS, V19)}
        !          15812: @findex gnus-Summary-prev-same-subject @r{(V19)}
        !          15813: @item C-M-n
        !          15814: @itemx C-M-p
        !          15815: In the Summary buffer, read the next or previous article with the same
        !          15816: subject as the current article.
        !          15817: @end table
        !          15818: 
        !          15819: @ignore
        !          15820: @node Where to Look
        !          15821: @subsection Where to Look Further
        !          15822: 
        !          15823: @c Too many references to the name of the manual if done with xref in TeX!
        !          15824: @sc{gnus} is powerful and customizable.  Here are references to a few
        !          15825: @ifinfo
        !          15826: additional topics:
        !          15827: 
        !          15828: @end ifinfo
        !          15829: @iftex
        !          15830: additional topics in @cite{The GNUS Manual}:
        !          15831: 
        !          15832: @itemize @bullet
        !          15833: @item
        !          15834: Follow discussions on specific topics.@*
        !          15835: See section ``Thread-based Reading''.
        !          15836: 
        !          15837: @item
        !          15838: Read digests. See section ``Digest Articles''
        !          15839: 
        !          15840: @item
        !          15841: Refer to and jump to the parent of the current article.@*
        !          15842: See section ``Referencing Articles''.
        !          15843: 
        !          15844: 
        !          15845: @item
        !          15846: Refer to articles by using Message-IDs included in the messages.@*
        !          15847: See section ``Article Commands''.
        !          15848: 
        !          15849: @item
        !          15850: Save articles. See section ``Saving Articles''.
        !          15851: 
        !          15852: @item
        !          15853: Create filters that preselect which articles you will see, according to
        !          15854: regular expressions in the articles or their headers.@*
        !          15855: See section ``Kill File''.
        !          15856: 
        !          15857: @item
        !          15858: Send an article to a newsgroup.@*
        !          15859: See section ``Posting Articles''.
        !          15860: @end itemize
        !          15861: @end iftex
        !          15862: @ifinfo
        !          15863: @itemize @bullet
        !          15864: @item
        !          15865: Follow discussions on specific topics.@*
        !          15866: @xref{Thread-based Reading, , Reading Based on Conversation Threads,
        !          15867: gnus, The GNUS Manual}.
        !          15868: 
        !          15869: @item
        !          15870: Read digests. @xref{Digest Articles, , , gnus, The GNUS Manual}.
        !          15871: 
        !          15872: @item
        !          15873: Refer to and jump to the parent of the current article.@*
        !          15874: @xref{Referencing Articles, , , gnus, The GNUS Manual}.
        !          15875: 
        !          15876: 
        !          15877: @item
        !          15878: Refer to articles by using Message-IDs included in the messages.@*
        !          15879: @xref{Article Commands, , , gnus, The GNUS Manual}.
        !          15880: 
        !          15881: @item
        !          15882: Save articles. @xref{Saving Articles, , , gnus, The GNUS Manual}.
        !          15883: 
        !          15884: @item
        !          15885: Create filters that preselect which articles you will see, according to
        !          15886: regular expressions in the articles or their headers.@*
        !          15887: @xref{Kill File, , , gnus, The GNUS Manual}. 
        !          15888: 
        !          15889: @item
        !          15890: Send an article to a newsgroup.@*
        !          15891: @xref{Posting Articles, , , gnus, The GNUS Manual}.
        !          15892: @end itemize
        !          15893: @end ifinfo
        !          15894: @end ignore
        !          15895: 
        !          15896: @node Calendar/Diary
        !          15897: @section Calendar and Diary
        !          15898: 
        !          15899: The calendar facility in Emacs 19 is almost completely new, and it
        !          15900: comes with a diary feature.  You can use the diary to keep track of
        !          15901: appointments, anniversaries, and other events.
        !          15902: @c ??? reference to top node, Diary in GNU Emacs Calendar 
        !          15903: @c @xref{diary, , Diary, calendar, The GNU Emacs Calendar}, for more
        !          15904: @c complete information.
        !          15905: 
        !          15906: To use the diary, you must write diary entries in a particular file,
        !          15907: called your @dfn{diary file}.  Its name is @file{~/diary}.  Emacs
        !          15908: displays the entries for particular dates by finding them in the diary
        !          15909: file, formatting them, and displaying them in a diary display buffer.
        !          15910: 
        !          15911: @menu
        !          15912: * Calendar::                   New features of the calendar proper.
        !          15913: * Entries: Diary Entries.      The location and form of a diary entry.
        !          15914: * New Entries::                        Inserting diary entries using the calendar.
        !          15915: * Displaying Diary::            How to display diary entries from the calendar.
        !          15916: * European Calendar Style ::    Day-month-year style for dates.
        !          15917: * Simple and Fancy::            The diary has two modes for display.
        !          15918: * Other Diary Features::        The diary has many advanced commands.
        !          15919: * Startup Diary::              How to display your diary when you start Emacs.
        !          15920: * Printing Diary::             Print selected entries of the diary.
        !          15921: @end menu
        !          15922: 
        !          15923: @node Calendar
        !          15924: @subsection Calendar
        !          15925: @cindex calendar @r{(V19)}
        !          15926: 
        !          15927: In Emacs 19 you can use ordinary Emacs cursor commands to move through
        !          15928: the calendar, which scrolls automatically to display different months or
        !          15929: different years.  Character motion translates to days, line motion to
        !          15930: weeks, sentence and paragraph motion to months, and page motion to
        !          15931: years.  The vertical and horizontal scroll commands also handle the
        !          15932: calendar suitably.
        !          15933: 
        !          15934: @c The index entries for the key bindings of Calendar and Diary modes
        !          15935: @c are commented out because they don't seem very useful.
        !          15936: @c @kindex p d (Calendar mode)
        !          15937: @c @kindex g d (Calendar mode)
        !          15938: @c @kindex . (Calendar mode)
        !          15939: @kbd{p d} displays the selected date as a day within the year.  @kbd{g
        !          15940: d} selects a date given as month, day, year.  Type @kbd{.} to go back
        !          15941: to today's date.
        !          15942: 
        !          15943: @c @kindex M-= (Calendar mode)
        !          15944: @findex calendar-count-days-region @r{(V19)}
        !          15945: The command @kbd{M-=}, which normally gives the number of lines in the
        !          15946: region, in Calendar mode gives the number of days in the region
        !          15947: (@code{calendar-count-days-region}).
        !          15948: 
        !          15949: The calendar facility also knows about other important calendars.  The
        !          15950: commands for these come in pairs; the commands to convert @emph{to}
        !          15951: another calendar start with the @kbd{p} prefix (short for ``print''),
        !          15952: and the commands to convert from another calendar start with the @kbd{g}
        !          15953: prefix (short for ``go to'').  Here is a complete list:
        !          15954: 
        !          15955: @c !!! Insert line breaks to prevent overfull hboxes.
        !          15956: @table @asis
        !          15957: @item @kbd{g a}, @kbd{p a}
        !          15958: @findex calendar-print-astro-date @r{(V19)}
        !          15959: @findex calendar-goto-astro-date @r{(V19)}
        !          15960: @cindex astronomical calendar
        !          15961: @cindex Julian day number
        !          15962: The astronomical calendar, a simple count of days elapsed since noon,
        !          15963: Monday, January 1, 4713 B.C. on the Julian calendar.  The number of days
        !          15964: elapsed is also called the @dfn{Julian day number}
        !          15965: (@code{calendar-goto-astro-date}, @code{calendar-print-astro-date}).
        !          15966: 
        !          15967: @item @kbd{g c}, @kbd{p c}
        !          15968: @c @kindex g c (Calendar mode)
        !          15969: @c @kindex p c (Calendar mode)
        !          15970: @findex calendar-print-iso-date @r{(V19)}
        !          15971: @findex calendar-goto-iso-date @r{(V19)}
        !          15972: @cindex ISO commercial calendar
        !          15973: ISO commercial calendar@* 
        !          15974: (@code{calendar-goto-iso-date}, @code{calendar-print-iso-date}).
        !          15975: 
        !          15976: @item @kbd{g f}, @kbd{p f}
        !          15977: @c @kindex p f (Calendar mode)
        !          15978: @findex calendar-goto-french-date @r{(V19)}
        !          15979: @findex calendar-print-french-date @r{(V19)}
        !          15980: @cindex French revolutionary calendar
        !          15981: @c !!! added @* to prevent overfull hbox
        !          15982: French revolutionary calendar@*
        !          15983: (@code{calendar-goto-french-date},@*
        !          15984: @code{calendar-print-french-date}).
        !          15985: 
        !          15986: @item @kbd{g h}, @kbd{p h}
        !          15987: @c @kindex g h (Calendar mode)
        !          15988: @c @kindex p h (Calendar mode)
        !          15989: @findex calendar-print-hebrew-date @r{(V19)}
        !          15990: @findex calendar-goto-hebrew-date @r{(V19)}
        !          15991: @cindex Hebrew calendar
        !          15992: @c !!! added @* to prevent overfull hbox
        !          15993: Hebrew calendar@*
        !          15994: (@code{calendar-goto-hebrew-date},@*
        !          15995: @code{calendar-print-hebrew-date}).
        !          15996: 
        !          15997: @item @kbd{g i}, @kbd{p i}
        !          15998: @c @kindex g i (Calendar mode)
        !          15999: @c @kindex p i (Calendar mode)
        !          16000: @findex calendar-print-islamic-date @r{(V19)}
        !          16001: @findex calendar-goto-islamic-date @r{(V19)}
        !          16002: @cindex Islamic calendar
        !          16003: @c !!! added @* to prevent overfull hbox
        !          16004: Islamic calendar@*
        !          16005: (@code{calendar-goto-islamic-date},@*
        !          16006: @code{calendar-print-islamic-date}).
        !          16007: 
        !          16008: @item @kbd{g j}, @kbd{p j}
        !          16009: @c @kindex g j (Calendar mode)
        !          16010: @c @kindex p j (Calendar mode)
        !          16011: @findex calendar-print-julian-date @r{(V19)}
        !          16012: @findex calendar-goto-julian-date @r{(V19)}
        !          16013: @cindex Julian calendar
        !          16014: @c !!! added @* to prevent overfull hbox
        !          16015: Julian calendar@*
        !          16016: (@code{calendar-goto-julian-date},@*
        !          16017: @code{calendar-print-julian-date}).
        !          16018: 
        !          16019: @item @kbd{p m}
        !          16020: @c @kindex p m (Calendar mode)
        !          16021: @findex calendar-print-mayan-date @r{(V19)}
        !          16022: @cindex Mayan calendar
        !          16023: Mayan calendar (@code{calendar-print-mayan-date}).
        !          16024: @end table
        !          16025: 
        !          16026: @ignore
        !          16027:   Several commands are needed to handle selecting dates in the Mayan
        !          16028: calendar.
        !          16029: 
        !          16030: @table @kbd
        !          16031: @item g m l @var{baktun}.@var{katun}.@var{tun}.@var{uinic}.@var{kin} @key{RET}
        !          16032: @cindex long count @r{(V19)}
        !          16033: Move point to a date specified in the Mayan long count calendar
        !          16034: (@code{calendar-goto-long-count-date}).  The argument consists of numbers
        !          16035: separated by periods.
        !          16036: @item g m p t @var{number} @var{name} @key{RET}
        !          16037: @cindex tzolkin @r{(V19)}
        !          16038: Move point to the previous occurrence of a specified date in the Mayan
        !          16039: tzolkin calendar (@code{calendar-previous-tzolkin-date}).  Here @var{name}
        !          16040: is one of the twenty tzolkin day names, and @var{number} is between 1 and 13.
        !          16041: @item g m n t @var{number} @var{name} @key{RET}
        !          16042: Move point to the next occurrence of a specified date in the
        !          16043: tzolkin calendar (@code{calendar-next-tzolkin-date}).
        !          16044: @item g m p h @var{kin} @var{uinal} @key{RET}
        !          16045: @cindex haab @r{(V19)}
        !          16046: Move point to the previous occurrence of a specified date in the Mayan
        !          16047: haab calendar (@code{calendar-previous-haab-date}).  Here @var{uinal}
        !          16048: is a haab month name, and @var{kin} is a number from 1 to 19 (or 0).
        !          16049: @item g m n h @var{kin} @var{uinal} @key{RET}
        !          16050: Move point to the next occurrence of a specified date in the
        !          16051: haab calendar (@code{calendar-next-haab-date}).
        !          16052: @item g m p c @var{number} @var{name} @var{kin} @var{uinal} @key{RET}
        !          16053: @cindex calendar round @r{(V19)}
        !          16054: Move point to the previous occurrence of a specified date in the Mayan
        !          16055: calendar round (@code{calendar-previous-calendar-round-date}).  Specify
        !          16056: a tzolkin date followed by a haab date.
        !          16057: @item g m n c @var{number} @var{name} @var{kin} @var{uinal} @key{RET}
        !          16058: Move point to the next occurrence of a specified date in the 
        !          16059: calendar round (@code{calendar-next-calendar-round-date}).
        !          16060: @end table
        !          16061: @end ignore
        !          16062: 
        !          16063: @findex calendar-cursor-holidays @r{(V19)}
        !          16064: @findex mark-calendar-holidays @r{(V19)}
        !          16065: @findex calendar-unmark @r{(V19)}
        !          16066: The calendar also knows the dates of standard holidays.  Type @kbd{h}
        !          16067: (@code{calendar-cursor-holidays}) to display a list of holidays for the
        !          16068: selected date.  This list appears in another window.  Type @kbd{x}
        !          16069: (@code{mark-calendar-holidays}) to mark each day that is a holiday with
        !          16070: @samp{*} in the calendar itself.  The command @kbd{u}
        !          16071: (@code{calendar-unmark}) turns off this marking.
        !          16072: 
        !          16073: @findex holidays @r{(V19)}
        !          16074: At any time, you can use @kbd{M-x holidays} to display a list of
        !          16075: holidays for the present month and the preceding and following months.
        !          16076: 
        !          16077: @node Diary Entries
        !          16078: @subsection Diary Entries
        !          16079: @cindex diary entries (V19)
        !          16080: 
        !          16081: @vindex diary-file @r{(V19)}
        !          16082: To use the diary feature, you must write @dfn{diary entries} that
        !          16083: describe plans associated with particular dates, and put them in your
        !          16084: @dfn{diary file}, which is normally the file @file{~/diary}.  You can
        !          16085: specify a different name for it by setting the variable
        !          16086: @code{diary-file}; you would do this before using any of the commands
        !          16087: that operate on the diary.
        !          16088: 
        !          16089: Diary file entries follow a simple convention: begin entries with a date
        !          16090: at the beginning of a line, followed optionally by a time, and then by
        !          16091: the text of the entry:
        !          16092: 
        !          16093: @example
        !          16094: @var{date} @var{optional-time-of-day} @var{text-of-entry}
        !          16095: @end example
        !          16096: 
        !          16097: @noindent
        !          16098: To continue an entry over two or more lines, indent the second and
        !          16099: subsequent lines.  The lines of the entry after the first are called
        !          16100: @dfn{continuation lines}.  Other lines in the diary file that are not
        !          16101: part of any entry are comment lines; Emacs does not display these.
        !          16102: 
        !          16103: When you make diary entries using Calendar mode, Emacs inserts the date
        !          16104: for you in the appropriate format and places the cursor so you can type
        !          16105: the text of the entry.
        !          16106: 
        !          16107: You can write entries in any order and Emacs will display the entries by
        !          16108: date.  However, time-of-day entries can be sorted chronologically only
        !          16109: in a diary mode called Fancy mode; in Simple mode, Emacs displays
        !          16110: time-of-day entries in their order in the diary file.
        !          16111: 
        !          16112: @node Displaying Diary
        !          16113: @subsection Calendar Commands to Display Diary Entries
        !          16114: @cindex diary display (V19)
        !          16115: @cindex display of diary (V19)
        !          16116: 
        !          16117: In Calendar mode, use the following commands to display your diary
        !          16118: entries:
        !          16119: 
        !          16120: @table @kbd
        !          16121: @findex view-diary-entries @r{(V19)}
        !          16122: @c @kindex d (Calendar mode) @r{(V19)}
        !          16123: @item d
        !          16124: Display any diary entries for the date under the cursor
        !          16125: (@code{view-diary-entries}).
        !          16126: 
        !          16127: With a numeric argument, Emacs shows the diary entries for that many
        !          16128: successive days, starting with and including the date under the cursor.
        !          16129: Thus, @kbd{2 d} displays all the entries for the selected date and for
        !          16130: the following day.
        !          16131: 
        !          16132: @findex show-all-diary-entries @r{(V19)}
        !          16133: @c @kindex s (Calendar mode) @r{(V19)}
        !          16134: @item s
        !          16135: Display your entire diary file (@code{show-all-diary-entries}).
        !          16136: 
        !          16137: @findex mark-diary-entries @r{(V19)}
        !          16138: @c @kindex m (Calendar mode) @r{(V19)}
        !          16139: @item m
        !          16140: In the calendar, mark all visible dates that have diary entries
        !          16141: (@code{mark-diary-entries}).
        !          16142: 
        !          16143: @findex calendar-unmark @r{(V19)}
        !          16144: @c @kindex u (Calendar mode) @r{(V19)}
        !          16145: @item u
        !          16146: Unmark the calendar (@code{calendar-unmark}).
        !          16147: @end table
        !          16148: 
        !          16149: At any time, not just in Calendar mode, you can display today's diary
        !          16150: entries by typing:
        !          16151: 
        !          16152: @findex diary @r{(V19)}
        !          16153: @example
        !          16154: M-x diary
        !          16155: @end example
        !          16156: 
        !          16157: @noindent
        !          16158: With a prefix argument @var{n}, this command displays diary entries for
        !          16159: @var{n} successive days, starting from and including today.
        !          16160: 
        !          16161: @node New Entries
        !          16162: @subsection Calendar Commands for Making Diary Entries
        !          16163: @cindex diary entries, inserting (V19)
        !          16164: 
        !          16165: Calendar mode provides several commands to help you make diary file
        !          16166: entries.  These commands work by visiting the diary file and inserting
        !          16167: the date information; you must finish the job by inserting the text of
        !          16168: the entry, and then save the diary file with @kbd{C-x C-s}.  The
        !          16169: commands are:
        !          16170: 
        !          16171: @table @kbd
        !          16172: @findex insert-diary-entry @r{(V19)}
        !          16173: @c @kindex i d (Calendar mode) @r{(V19)}
        !          16174: @item i d
        !          16175: Add a diary entry for the selected date in the calendar
        !          16176: (@code{insert-diary-entry}).
        !          16177: 
        !          16178: @findex insert-weekly-diary-entry @r{(V19)}
        !          16179: @c @kindex i w (Calendar mode) @r{(V19)}
        !          16180: @item i w
        !          16181: Add a diary entry for the selected day of the week
        !          16182: (@code{insert-weekly-diary-entry}).  This entry is displayed each week
        !          16183: on the selected day.
        !          16184: 
        !          16185: @findex insert-monthly-diary-entry @r{(V19)}
        !          16186: @c @kindex i m (Calendar mode) @r{(V19)}
        !          16187: @item i m
        !          16188: Add a diary entry for the selected day of the month
        !          16189: (@code{insert-monthly-diary-entry}).  This entry is displayed each month
        !          16190: on the selected day.
        !          16191: 
        !          16192: @findex insert-yearly-diary-entry @r{(V19)}
        !          16193: @c @kindex i y (Calendar mode) @r{(V19)}
        !          16194: @item i y
        !          16195: Add a diary entry for the selected day of the year
        !          16196: (@code{insert-yearly-diary-entry}).  This entry is displayed each year
        !          16197: on the selected day.
        !          16198: @end table
        !          16199: 
        !          16200: Here are commands for entering more complex kinds of diary entries in
        !          16201: Calendar mode.  These kinds of entries operate properly only in Fancy
        !          16202: Diary Display mode (@pxref{Simple and Fancy}).
        !          16203: 
        !          16204: @table @kbd
        !          16205: @findex insert-anniversary-diary-entry @r{(V19)}
        !          16206: @c @kindex i a (Calendar mode diary) @r{(V19)}
        !          16207: @item i a
        !          16208: Add an anniversary diary entry for the selected date
        !          16209: (@code{insert-anniversary-diary-entry}).
        !          16210: 
        !          16211: Select the date you want remembered, in the proper year---if it is a
        !          16212: birthday, remember to go to the person's year of birth!  Then type
        !          16213: @kbd{i a} and enter the text of the entry.
        !          16214: 
        !          16215: In the textual part of the entry you can type @samp{%d}.  When Emacs
        !          16216: displays the entry in the diary buffer, the @samp{%d} is replaced by the
        !          16217: number of years since the date.  Thus, if you use @samp{%d years old} as
        !          16218: the text of the entry, it will display as @samp{53 years old} on the
        !          16219: 53rd birthday.
        !          16220: 
        !          16221: @findex insert-cyclic-diary-entry @r{(V19)}
        !          16222: @c @kindex i c (Calendar mode diary) @r{(V19)}
        !          16223: @item i c
        !          16224: Add a cyclic diary entry starting at the date
        !          16225: (@code{insert-cyclic-diary-entry}).  An entry is displayed on a
        !          16226: specified starting date and then is repeatedly displayed at the
        !          16227: specified interval.  This is useful for ten day cycles of preventive
        !          16228: maintenance and similar activities.
        !          16229: 
        !          16230: To use this command, first select the start date.  The command reads the
        !          16231: interval (the number of days between repetitions) using the minibuffer,
        !          16232: then inserts the beginning of the entry.
        !          16233: 
        !          16234: @findex insert-block-diary-entry @r{(V19)}
        !          16235: @c @kindex i b (Calendar mode diary) @r{(V19)}
        !          16236: @item i b
        !          16237: Add a block diary entry for the current region
        !          16238: (@code{insert-block-diary-entry}).  With a block entry, Emacs
        !          16239: writes the same message in the display for successive days.  
        !          16240: 
        !          16241: Position point and mark at the beginning and end of the block of days
        !          16242: you want entered and type @kbd{i b}.  This sets up the diary entry's
        !          16243: date info and positions point so you can write the text of the entry.
        !          16244: People usually use this command for trips or vacations.
        !          16245: @end table
        !          16246: 
        !          16247: @node European Calendar Style
        !          16248: @subsection  European Calendar Style 
        !          16249: @cindex European date style (Calendar, V19)
        !          16250: @cindex American date style (Calendar, V19)
        !          16251: @cindex dates, style of writing (Calendar, V19)
        !          16252: 
        !          16253: By default, Emacs interprets and displays diary dates in civilian
        !          16254: American form, @samp{@var{month}/@var{day}/@var{year}}:
        !          16255: @samp{2/15/1993}, or @samp{February 15, 1993}.
        !          16256: 
        !          16257: @vindex european-calendar-style @r{(V19)}
        !          16258: @cindex European calendar style (V19)
        !          16259: Alternatively, you can specify the European calendar style for writing
        !          16260: dates: @samp{@var{day}/@var{month}/@var{year}}, @samp{15/2/1993} or
        !          16261: @samp{15 February 1993}.  To do this, set the variable
        !          16262: @code{european-calendar-style} to @code{t}, before using any calendar or
        !          16263: diary command.  This also affects display of dates.
        !          16264: 
        !          16265:   Here's how to do this in your @file{.emacs} file:
        !          16266: 
        !          16267: @example
        !          16268: (setq european-calendar-style t)
        !          16269: @end example
        !          16270: 
        !          16271: @node Simple and Fancy
        !          16272: @subsection Simple and Fancy Diary Display
        !          16273: @cindex Simple Diary mode (V19)
        !          16274: @cindex Fancy Diary mode (V19)
        !          16275: 
        !          16276: There are two modes for displaying a subset of diary entries: Simple
        !          16277: mode and Fancy mode.  Fancy mode provides a more dramatic display for
        !          16278: the diary, and can also display the actual matching date for diary
        !          16279: entries that match more than one date.
        !          16280: 
        !          16281: @vindex diary-display-hook @r{(V19)}
        !          16282: @findex fancy-diary-display @r{(V19)}
        !          16283: By default, Emacs uses Simple mode, which is quicker than Fancy mode.
        !          16284: Another advantage of Simple mode is that you can edit the displayed
        !          16285: diary entries ``in place'' and save them.  When you use Fancy mode, it
        !          16286: is useless to edit the displayed subset of the diary; instead you must
        !          16287: visit the diary file separately.  To select Fancy mode, set
        !          16288: @code{diary-display-hook} to @code{fancy-diary-display} like this:
        !          16289: 
        !          16290: @example
        !          16291: (setq diary-display-hook 'fancy-diary-display)
        !          16292: @end example
        !          16293: 
        !          16294: @node Other Diary Features
        !          16295: @subsection Other Diary Features
        !          16296: 
        !          16297: Here are some additional diary features.  These will be explained in
        !          16298: full in @cite{The GNU Emacs Extensions Manual}.
        !          16299: 
        !          16300: You can schedule meetings on a date such as the first Tuesday of every
        !          16301: month.  This is called an @dfn{offset} date.  The diary has commands
        !          16302: for specifying such meetings, but not in Calendar mode.  To create
        !          16303: such an entry, you need to edit the diary file yourself.
        !          16304: @c !!! reference to diary offset in
        !          16305: @c !!! xref{diary offset, , Offset Events, calendar, The GNU Emacs
        !          16306: @c !!! Calendar}, for more information.
        !          16307: 
        !          16308: You can make entries according to Hebrew and Islamic dates.  Calendar
        !          16309: mode provides commands of the form @kbd{i h d} to add a diary entry
        !          16310: for the Hebrew date corresponding to the selected date and @kbd{i i d}
        !          16311: to add a diary entry for the Islamic date corresponding to the selected
        !          16312: date.  You can make entries that repeat every week, month, or year.
        !          16313: Before using these commands, you must set the
        !          16314: @code{nongregorian-diary-listing-hook} and the
        !          16315: @code{nongregorian-diary-marking-hook} in your @file{.emacs} file.
        !          16316: @c !!! reference to Hebrew/Islamic Entries in The GNU Emacs Calendar
        !          16317: @c !!! @xref{Hebrew/Islamic Entries, , Hebrew- and Islamic-Date Diary
        !          16318: @c !!! Entries, calendar, The GNU Emacs Calendar}.
        !          16319: 
        !          16320: You can include other diary files in your diary display.  This way, a
        !          16321: group of people can share a common diary file.  
        !          16322: @c !!! reference to Including Diary Files in The GNU Emacs Calendar
        !          16323: @c !!! xref{Including Diary Files, , Including Other Diary Files, calendar, The
        !          16324: @c !!! GNU Emacs Calendar}.
        !          16325: 
        !          16326: @node Startup Diary
        !          16327: @subsection Displaying your Diary on Emacs Startup
        !          16328: @cindex diary and Emacs startup (V19)
        !          16329: 
        !          16330: If you start a new Emacs each day, you might want to display your diary
        !          16331: automatically at that time.  To do so, put this in your @file{.emacs}
        !          16332: file:
        !          16333: 
        !          16334: @example
        !          16335: (diary)
        !          16336: @end example
        !          16337: 
        !          16338: If you want to see both the calendar and your diary at startup, use this
        !          16339: instead:
        !          16340: 
        !          16341: @example
        !          16342: @group
        !          16343: (setq view-diary-entries-initially t)
        !          16344: (calendar)
        !          16345: @end group
        !          16346: @end example
        !          16347: 
        !          16348: @node Printing Diary
        !          16349: @subsection Printing the Displayed Part of the Diary
        !          16350: @cindex Printing diary (V19)
        !          16351: 
        !          16352: @findex print-diary-entries @r{(V19)}
        !          16353: To print the selected diary entries as they appear on the screen, use
        !          16354: @kbd{M-x print-diary-entries}.  The same variables that customize
        !          16355: @code{lpr-buffer} also affect this command.
        !          16356: 
        !          16357: In Simple mode, the diary display buffer uses selective display
        !          16358: (@pxref{Selective Display}).  This means that what you see on the screen
        !          16359: is just part of the text in the Emacs buffer.  The diary entries that
        !          16360: don't apply to the dates you asked for are still in the buffer, but
        !          16361: hidden.  The ordinary printing commands such as @code{lpr-buffer} would
        !          16362: not do what you want; they print the entire text, including the hidden
        !          16363: parts.  This is why we need @code{print-diary-entries}.
        !          16364: 
        !          16365: @node Version Control
        !          16366: @section Version Control
        !          16367: @cindex version control
        !          16368: 
        !          16369:   @dfn{Version control systems} are packages that can record multiple
        !          16370: versions of a source file, usually storing the unchanged parts of the
        !          16371: file just once.  Version control systems also record history information
        !          16372: such as the creation time of each version, who created it, and a 
        !          16373: description of what was changed in that version.
        !          16374: 
        !          16375:   The GNU project recommends the version control system known as RCS,
        !          16376: which is free software and available from the Free Software Foundation.
        !          16377: Emacs supports use of either RCS or SCCS (a proprietary, but widely
        !          16378: used, version control system that is not quite as powerful as RCS)
        !          16379: through a facility called VC.  The same Emacs commands work with either
        !          16380: RCS or SCCS, so you hardly have to know which one of them you are
        !          16381: using.
        !          16382: 
        !          16383: @menu
        !          16384: * Concepts of VC::
        !          16385: * Editing with VC::
        !          16386: * Variables for Check-in/out::
        !          16387: * Comparing Versions::
        !          16388: * VC Status::
        !          16389: * Renaming and VC::
        !          16390: * Snapshots::
        !          16391: * Log Entries::
        !          16392: * Change Logs and VC::
        !          16393: * Version Headers::
        !          16394: @end menu
        !          16395: 
        !          16396: @node Concepts of VC
        !          16397: @subsection Concepts of Version Control
        !          16398: @cindex RCS
        !          16399: @cindex SCCS
        !          16400: @cindex master file
        !          16401: @cindex registered file
        !          16402: @cindex work file
        !          16403: 
        !          16404:    When a file is under version control, we also say that it is
        !          16405: @dfn{registered} in the version control system.  Each registered file
        !          16406: has a corresponding @dfn{master file} which represents the file's
        !          16407: present state plus its change history, so that you can reconstruct from
        !          16408: it either the current version or any specified earlier version.  Usually
        !          16409: the master file also records a change comment for each version.
        !          16410: 
        !          16411:   The file that is maintained under version control is sometimes called
        !          16412: the @dfn{work file} corresponding to its master file.
        !          16413: 
        !          16414: @cindex checking out files
        !          16415: @cindex checking in files
        !          16416: @cindex locking and version control
        !          16417:    To examine a file, you @dfn{check it out}.  This extracts a version
        !          16418: of the file (typically, the most recent) from the master.  If you want
        !          16419: to edit the file, you must check it out @dfn{locked}.  Only one user can
        !          16420: do this at a time for any given source file.  When you are done with
        !          16421: your editing, you must @dfn{check in} the new version.  This records the
        !          16422: new version in the master file, and unlocks the source file so that
        !          16423: other people can lock it and thus modify it.
        !          16424: 
        !          16425:    These are the basic operations of version control.  
        !          16426: Checking in and checking out both use the single Emacs command
        !          16427: @w{@kbd{C-x C-q}} (@code{vc-toggle-read-only}).
        !          16428: 
        !          16429: @node Editing with VC
        !          16430: @subsection Editing with Version Control
        !          16431: 
        !          16432:   When you visit a file that is maintained using version control, the
        !          16433: mode line displays @samp{RCS} or @samp{SCCS} to inform you that version
        !          16434: control is in use, and also (in case you care) which low-level system
        !          16435: the file is actually stored in.  Normally, such a source file is
        !          16436: read-only, and the mode line indicates this with @samp{%%}.)
        !          16437: 
        !          16438:   These are the commands that you use to edit a file maintained with
        !          16439: version control:
        !          16440: 
        !          16441: @table @kbd
        !          16442: @item C-x C-q
        !          16443: Check the visited file in or out.
        !          16444: 
        !          16445: @item C-x v u
        !          16446: Revert the buffer and the file to the last checked in version.
        !          16447: 
        !          16448: @item C-x v c
        !          16449: Remove the last-entered change from the master for the visited file.
        !          16450: This undoes your last check-in.
        !          16451: 
        !          16452: @item C-x v i
        !          16453: Register the visited file in version control.
        !          16454: @end table
        !          16455: 
        !          16456: @noindent
        !          16457: (@kbd{C-x v} is the prefix key for version control commands; all of these
        !          16458: commands except for @kbd{C-x C-q} start with @kbd{C-x v}.)
        !          16459: 
        !          16460: @kindex C-x C-q @r{(V19)}
        !          16461: @findex vc-toggle-read-only @r{(V19)}
        !          16462:   If you want to edit the file, type @kbd{C-x C-q}
        !          16463: (@code{vc-toggle-read-only}).  This @dfn{checks out} and locks the file,
        !          16464: so that you can edit it.  The file is writable after check-out, but only
        !          16465: for you, not for anyone else.
        !          16466: 
        !          16467: @vindex vc-make-backups @r{(V19)}
        !          16468:   Emacs does not save backup files for source files that are maintained
        !          16469: with version control.  If you want to make backup files despite version
        !          16470: control, set the variable @code{vc-make-backups} to a non-@code{nil} value.
        !          16471: 
        !          16472:   When you are finished editing the file, type @kbd{C-x C-q} again.
        !          16473: When used on a file that is checked out, this command checks the file
        !          16474: in.  But check-in does not start immediately; first, you must enter a
        !          16475: @dfn{log entry}---a description of the changes in the new version.
        !          16476: @kbd{C-x C-q} pops up a buffer for you to enter this in.  When you are
        !          16477: finished typing in the log entry, type @kbd{C-c C-c} to terminate it; this is
        !          16478: when actual check-in takes place.
        !          16479: 
        !          16480:   Once you have checked in your changes, the file is unlocked, so that
        !          16481: other users can lock it and modify it.
        !          16482: 
        !          16483: @vindex vc-keep-workfiles @r{(V19)}
        !          16484:   Normally the work file exists all the time, whether it is locked or
        !          16485: not.  If you set @code{vc-keep-workfiles} to @code{nil}, then checking
        !          16486: in a new version with @kbd{C-x C-q} deletes the work file; but any
        !          16487: attempt to visit the file with Emacs creates it again.
        !          16488: 
        !          16489:   Actually, it is not impossible to lock a file that someone else has
        !          16490: locked.  If you try to check out a file that is locked, @kbd{C-x C-q}
        !          16491: asks you whether you want to ``steal the lock.''  If you say yes, the
        !          16492: file becomes locked by you, but a message is sent to the person who had
        !          16493: formerly locked the file, to inform him or her of what has happened.
        !          16494: 
        !          16495: @kindex C-x v u @r{(V19)}
        !          16496: @findex vc-revert-buffer @r{(V19)}
        !          16497:   If you want to discard your current set of changes and revert to the
        !          16498: last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}).
        !          16499: This cancels your last check-out, leaving the file unlocked.  If you want
        !          16500: to make a different set of changes, you must first check the file out
        !          16501: again.  @kbd{C-x v u} requies confirmation, unless it sees that 
        !          16502: you haven't made any changes since the last checked-in version.
        !          16503: 
        !          16504:   @kbd{C-x v u} is also the command to use if you lock a file and then
        !          16505: don't actually change it.
        !          16506: 
        !          16507: @kindex C-x v c @r{(V19)}
        !          16508: @findex vc-cancel-version @r{(V19)}
        !          16509:   You can even cancel a change after checking it in, with @kbd{C-x v c}
        !          16510: (@code{vc-cancel-version}).  Normally, @kbd{C-x v c} reverts your
        !          16511: workfile and buffer to the previous version (the one that precedes the
        !          16512: version that is deleted), but you can prevent the reversion by giving
        !          16513: the command a prefix argument.  Then the buffer does not change.
        !          16514: 
        !          16515:   This command with a prefix argument is useful when you have checked in
        !          16516: a change and then discover a trivial error in it; you can cancel the
        !          16517: erroneous check-in, fix the error, and repeat the check-in.
        !          16518: 
        !          16519:   Be careful when invoking @kbd{C-x v c}, as it is easy to throw away a
        !          16520: lot of work with it.  To help you be careful, this command always asks
        !          16521: for confirmation with @samp{yes}.
        !          16522: 
        !          16523: @kindex C-x v i @r{(V19)}
        !          16524: @findex vc-register @r{(V19)}
        !          16525:   You can register the visited file for version control using 
        !          16526: @w{@kbd{C-x v i}} (@code{vc-register}).  This uses RCS if RCS 
        !          16527: is installed on your system; otherwise, it uses SCCS.
        !          16528: 
        !          16529:   By default, the initial version number is 1.1.  If you want to use a
        !          16530: different number, give @kbd{C-x v i} a prefix argument; then it reads
        !          16531: the initial version number using the minibuffer.
        !          16532: 
        !          16533:   After @kbd{C-x v i}, the file is unlocked and read-only.  Type
        !          16534: @kbd{C-x C-q} if you wish to edit it.
        !          16535: 
        !          16536: @vindex vc-initial-comment @r{(V19)}
        !          16537:   If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads
        !          16538: an initial comment (much like a log entry) to describe the purpose of
        !          16539: this source file.
        !          16540: 
        !          16541: @node Variables for Check-in/out
        !          16542: @subsection Variables Affecting Check-in and Check-out
        !          16543: @c There is no need to tell users about vc-master-templates.
        !          16544: 
        !          16545: @vindex vc-suppress-confirm @r{(V19)}
        !          16546:   If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q}
        !          16547: and @kbd{C-x v i} can save the current buffer without asking, and
        !          16548: @kbd{C-x v u} also operates without asking for confirmation.
        !          16549: (This variable does not affect @kbd{C-x v c}; that is so drastic
        !          16550: that it should always ask for confirmation.)
        !          16551: 
        !          16552: @vindex vc-command-messages @r{(V19)}
        !          16553:   VC mode does much of its work by running the shell commands for RCS
        !          16554: and SCCS.  If @code{vc-command-messages} is non-@code{nil}, VC displays
        !          16555: messages to indicate which shell commands it runs, and additional
        !          16556: messages when the commands finish.
        !          16557: 
        !          16558:   Normally, VC assumes that it can deduce the locked/unlocked state of
        !          16559: files by looking at the file permissions of the work file; this is
        !          16560: fast.  However, if the @file{RCS} or @file{SCCS} subdirectory is
        !          16561: actually a symbolic link, then VC does not trust the file permissions to
        !          16562: reflect this status.
        !          16563: 
        !          16564: @vindex vc-mistrust-permissions @r{(V19)}
        !          16565: You can specify the criterion for whether to trust the file permissions
        !          16566: by setting the variable @code{vc-mistrust-permissions}.  Its value may
        !          16567: be @code{t} (always mistrust the file permissions and check the master
        !          16568: file), @code{nil} (always trust the file permissions), or a function of
        !          16569: one argument which makes the decision.  The argument is the directory
        !          16570: name of the @file{RCS} or @file{SCCS} subdirectory.  A non-@code{nil}
        !          16571: value from the function says to mistrust the file permissions.
        !          16572: 
        !          16573:   If you find that the file permissions of work files are changed
        !          16574: erroneously, then you can set @code{vc-mistrust-permissions} to @code{t}
        !          16575: so that VC always checks the master file.
        !          16576: 
        !          16577: @node Log Entries
        !          16578: @subsection Log Entries
        !          16579: 
        !          16580: When you're editing an initial or change comment for inclusion in a
        !          16581: master file, finish your entry by typing @kbd{C-c C-c}.
        !          16582: 
        !          16583: @table @kbd
        !          16584: @item C-c C-c
        !          16585: Finish the comment edit normally (@code{vc-finish-logentry}).
        !          16586: This finishes check-in.
        !          16587: @end table
        !          16588: 
        !          16589: To abort check-in, just don't type @kbd{C-c C-c} in that buffer.  You
        !          16590: can switch buffers and do other editing.  As long as you don't try to
        !          16591: check in another file, the comment you were editing remains in its
        !          16592: buffer, and you can go back to that buffer at any time to complete the
        !          16593: check-in.
        !          16594: 
        !          16595: If you change several source files for the same reason, it is often
        !          16596: convenient to specify the same log entry for many of the files.  To do
        !          16597: this, use the history of previous log entries.  The commands
        !          16598: @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just
        !          16599: like the minibuffer history commands (except that they don't use the
        !          16600: minibuffer).
        !          16601: 
        !          16602: The history of previous log entries is actually stored in previous pages
        !          16603: of the log entry editing buffer; they are normally hidden by narrowing.
        !          16604: 
        !          16605: @vindex vc-log-mode-hook @r{(V19)}
        !          16606: Each time you check in a file, the log entry buffer is put into VC Log
        !          16607: mode, which involves running two hook variables: @code{text-mode-hook}
        !          16608: and @code{vc-log-mode-hook}.
        !          16609: 
        !          16610: @node Change Logs and VC
        !          16611: @subsection Change Logs and VC
        !          16612: 
        !          16613: Emacs users often record brief summaries of program changes in a file
        !          16614: called @file{ChangeLog}, which is kept in the same directory as the
        !          16615: source files, and is usually meant to be distributed along with the
        !          16616: source files.  You can maintain @file{ChangeLog} from the version
        !          16617: control logs with the following command.
        !          16618: 
        !          16619: @table @kbd
        !          16620: @item C-x v a
        !          16621: @kindex C-x v a @r{(V19)}
        !          16622: @findex vc-update-change-log @r{(V19)}
        !          16623: Visit the current directory's change log file and create new entries for
        !          16624: versions checked in since the most recent entry in the change log file
        !          16625: (@code{vc-update-change-log}).
        !          16626: 
        !          16627: This command works with RCS only; it does not work with SCCS.
        !          16628: @end table
        !          16629: 
        !          16630: For example, suppose the first line of @file{ChangeLog} is dated 10
        !          16631: April 1992, and suppose the only check-in since then was by Nathaniel
        !          16632: Bowditch to @file{rcs2log} on 8 May 1992 with log text @samp{Ignore log
        !          16633: messages that start with `#'.}.  Then @kbd{C-x v a} visits
        !          16634: @file{ChangeLog} and inserts text like this:
        !          16635: 
        !          16636: @example
        !          16637: @group
        !          16638: Fri May  8 21:45:00 1992  Nathaniel Bowditch  (nat@@apn.org)
        !          16639: 
        !          16640:         * rcs2log: Ignore log messages that start with `#'.
        !          16641: @end group
        !          16642: @end example
        !          16643: 
        !          16644: @noindent
        !          16645: You can then further edit as you wish.
        !          16646: 
        !          16647: A log entry whose text begins with @samp{#} is not copied to
        !          16648: @file{ChangeLog}.  For example, if you merely fix some misspellings in
        !          16649: comments, you can log the change with an entry beginning with @samp{#}
        !          16650: to avoid putting such trivia into @file{ChangeLog}.
        !          16651: 
        !          16652: When @kbd{C-x v a} adds several change log entries at once, it groups
        !          16653: related log entries together if they all are checked in by the same
        !          16654: author at nearly the same time.  If the log entries for several such
        !          16655: files all have the same text, it coalesces them into a single entry.
        !          16656: For example, suppose the most recent check-ins have the following log
        !          16657: entries:
        !          16658: 
        !          16659: @example
        !          16660: @exdent For @file{vc.texinfo}:
        !          16661: Fix expansion typos.
        !          16662: @exdent For @file{vc.el}:
        !          16663: Don't call expand-file-name.
        !          16664: @exdent For @file{vc-hooks.el}:
        !          16665: Don't call expand-file-name.
        !          16666: @end example
        !          16667: 
        !          16668: They appear like this in @file{ChangeLog}:
        !          16669: 
        !          16670: @example
        !          16671: @group
        !          16672: Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  (nat@@apn.org)
        !          16673: 
        !          16674:         * vc.texinfo: Fix expansion typos.
        !          16675: 
        !          16676:         * vc.el, vc-hooks.el: Don't call expand-file-name.
        !          16677: @end group
        !          16678: @end example
        !          16679: 
        !          16680: Normally, @kbd{C-x v a} separates log entries by a blank line, but you
        !          16681: can mark several related log entries to be clumped together (without an
        !          16682: intervening blank line) by starting the text of each related log entry
        !          16683: with a label of the form @w{@samp{@{@var{clumpname}@} }}.  The label
        !          16684: itself is not copied to @file{ChangeLog}.  For example, suppose the log
        !          16685: entries are:
        !          16686: 
        !          16687: @example
        !          16688: @exdent For @file{vc.texinfo}:
        !          16689: @{expand@} Fix expansion typos.
        !          16690: @exdent For @file{vc.el}:
        !          16691: @{expand@} Don't call expand-file-name.
        !          16692: @exdent For @file{vc-hooks.el}:
        !          16693: @{expand@} Don't call expand-file-name.
        !          16694: @end example
        !          16695: 
        !          16696: Then the text in @file{ChangeLog} looks like this:
        !          16697: 
        !          16698: @example
        !          16699: @group
        !          16700: Wed Apr  1 08:57:59 1992  Nathaniel Bowditch  (nat@@apn.org)
        !          16701: 
        !          16702:         * vc.texinfo: Fix expansion typos.
        !          16703:         * vc.el, vc-hooks.el: Don't call expand-file-name.
        !          16704: @end group
        !          16705: @end example
        !          16706: 
        !          16707: Normally, the log entry for file @file{foo} is displayed as @samp{* foo:
        !          16708: @var{text of log entry}}.  But by convention, the @samp{:} after
        !          16709: @file{foo} is omitted if the text of the log entry starts with
        !          16710: @w{@samp{(@var{functionname}): }}.  For example, if the log entry for
        !          16711: @file{vc.el} is @samp{(vc-do-command): Check call-process status.}, then
        !          16712: the text in @file{ChangeLog} looks like this:
        !          16713: 
        !          16714: @example
        !          16715: @group
        !          16716: Wed May  6 10:53:00 1992  Nathaniel Bowditch  (nat@@apn.org)
        !          16717: 
        !          16718:         * vc.el (vc-do-command): Check call-process status.
        !          16719: @end group
        !          16720: @end example
        !          16721: 
        !          16722: @node Comparing Versions
        !          16723: @subsection Comparing Versions
        !          16724: 
        !          16725: @findex vc-diff @r{(V19)}
        !          16726: @kindex C-x v = @r{(V19)}
        !          16727:   To compare two versions of a file, use @kbd{C-x v =} (@code{vc-diff}).
        !          16728: 
        !          16729:   Plain @kbd{C-x v =} compares the current buffer contents (saving them
        !          16730: in the file if necessary) with the last checked-in version of the file.
        !          16731: With a prefix argument, @kbd{C-x v =} reads a filename and two version
        !          16732: numbers, and compares those versions of the file you specify.
        !          16733: 
        !          16734:   If you supply a directory name instead of the name of a work file,
        !          16735: this command compares the two specified versions of all registered files
        !          16736: in that directory and its subdirectories.  You can also specify a
        !          16737: snapshot name (@pxref{Snapshots}) instead of one or both version
        !          16738: numbers.
        !          16739: 
        !          16740:   You can specify a checked-in version by its number; you can specify
        !          16741: the most recent checked-in version with @samp{-}; and you can specify
        !          16742: the current buffer contents with @samp{+}.  Thus, you can compare two
        !          16743: checked-in versions, or compare a checked-in version with the text you
        !          16744: are editing.
        !          16745: @c ??? + and - as args are not implemented yet.
        !          16746: 
        !          16747: @c ??? Currently it uses vc-diff-options.
        !          16748:   This command works by running the @code{diff} utility, getting the
        !          16749: options from the variable @code{diff-switches}.  It displays the output
        !          16750: in a special buffer in another window.
        !          16751: 
        !          16752: @node VC Status
        !          16753: @subsection VC Status Commands
        !          16754: 
        !          16755: @kindex C-x v l @r{(V19)}
        !          16756: @findex vc-print-log @r{(V19)}
        !          16757:   To get the detailed version control status of one file, type @kbd{C-x
        !          16758: v l} (@code{vc-print-log}).  It displays the history of changes to the
        !          16759: current file, including the text of the log entries.  The output appears
        !          16760: in a separate window.
        !          16761: 
        !          16762:   When you are working on a large program, it's often useful to find all
        !          16763: the files that are currently locked, or all the files maintained in
        !          16764: version control at all.  You can do so using these commands, both of
        !          16765: which operate on the branch of the file system starting at the current
        !          16766: directory.
        !          16767: 
        !          16768: @kindex C-x v d @r{(V19)}
        !          16769: @findex vc-directory @r{(V19)}
        !          16770:   You can use @kbd{C-x v d} (@code{vc-directory}) to show all the locked
        !          16771: files in or beneath the current directory.  This includes all files that
        !          16772: are locked by any user.
        !          16773: 
        !          16774:   With a prefix argument, @kbd{C-x v d} shows all the version control
        !          16775: activity in the current directory---it lists all files in or beneath the
        !          16776: current directory that are maintained with version control.
        !          16777: 
        !          16778: @node Renaming and VC
        !          16779: @subsection Renaming VC Work Files and Master Files
        !          16780: 
        !          16781: @findex vc-rename-file @r{(V19)}
        !          16782:   When you rename a registered file, you must also rename its master
        !          16783: file correspondingly to get proper results.  Use @code{vc-rename-file}
        !          16784: to rename the source file as you specify, and rename its master file
        !          16785: accordingly.  It also updates any snapshots (@pxref{Snapshots}) that
        !          16786: mention the file, so that they use the new name; despite this, the
        !          16787: snapshot thus modified may not completely work (@pxref{Snapshot
        !          16788: Caveats}).
        !          16789: 
        !          16790:   You cannot use @code{vc-rename-file} on a file that is locked by
        !          16791: someone else.
        !          16792: 
        !          16793:   @code{vc-rename-file} is not bound to a key because it's not likely
        !          16794: to be used frequently.
        !          16795: 
        !          16796: @node Snapshots
        !          16797: @subsection Snapshots
        !          16798: @cindex snapshots and version control
        !          16799: 
        !          16800:   A @dfn{snapshot} is a named set of file versions (one for each
        !          16801: registered file) that you can treat as a unit.  One important kind of
        !          16802: snapshot is a @dfn{release}, a (theoretically) stable version of the
        !          16803: system that is ready for distribution to users.
        !          16804: 
        !          16805: @menu
        !          16806: * Making Snapshots::           The snapshot facilities.
        !          16807: * Snapshot Caveats::           Things to be careful of, when using snapshots.
        !          16808: @end menu
        !          16809: 
        !          16810: @node Making Snapshots
        !          16811: @subsubsection Making and Using Snapshots
        !          16812: 
        !          16813:   There are two basic commands for snapshots; one makes a
        !          16814: snapshot with a given name, the other retrieves a named snapshot.
        !          16815: 
        !          16816: @table @code
        !          16817: @item C-x v s @var{name} @key{RET}
        !          16818: @kindex C-x v s @r{(V19)}
        !          16819: @findex vc-create-snapshot @r{(V19)}
        !          16820: Define the last saved versions of every registered file in or under the
        !          16821: current directory as a snapshot named @var{name}
        !          16822: (@code{vc-create-snapshot}).
        !          16823: 
        !          16824: @item C-x v r @var{name} @key{RET}
        !          16825: @kindex C-x v r @r{(V19)}
        !          16826: @findex vc-retrieve-snapshot @r{(V19)}
        !          16827: Check out all registered files at or below the current directory level
        !          16828: using whatever versions correspond to the snapshot @var{name}
        !          16829: (@code{vc-retrieve-snapshot}).
        !          16830: 
        !          16831: This function reports an error if any files are locked at or below the
        !          16832: current directory, without changing anything; this is to avoid
        !          16833: overwriting work in progress.
        !          16834: @end table
        !          16835: 
        !          16836: You shouldn't need to use @code{vc-retrieve-snapshot} very often; you
        !          16837: can get difference reports between two snapshots without retrieving
        !          16838: either one, using @kbd{C-x =} (@pxref{Comparing Versions}).  Thus,
        !          16839: retrieving a snapshot is only necessary if you need to study or compile
        !          16840: portions of the snapshot.
        !          16841: 
        !          16842: A snapshot uses a very small amount of resources---just enough to record
        !          16843: the list of file names and which version belongs to the snapshot.  Thus,
        !          16844: you need not hesitate to create snapshots whenever they are useful.
        !          16845: 
        !          16846: You can give a snapshot name as an argument to @kbd{C-x v =}
        !          16847: (@pxref{Comparing Versions}).  Thus, you can use it to compare a
        !          16848: snapshot against the current files, or two snapshots against each other,
        !          16849: or a snapshot against a named version.
        !          16850: 
        !          16851: @node Snapshot Caveats
        !          16852: @subsubsection Snapshot Caveats
        !          16853: 
        !          16854: @cindex named configurations (RCS)
        !          16855: VC's snapshot facilities are modeled on RCS's named-configuration
        !          16856: support.  They use RCS's native facilities for this, so under VC
        !          16857: snapshots made using RCS are visible even when you bypass VC.
        !          16858: 
        !          16859: @c !!! worded verbosely to avoid overfull hbox.
        !          16860: For SCCS, VC implements snapshots itself.  The files it uses contain
        !          16861: name/file/version-number triples.  These snapshots are visible only
        !          16862: through VC.
        !          16863: 
        !          16864: File renaming and deletion can create some difficulties with snapshots.
        !          16865: This is not a VC-specific problem, but a general design issue in version
        !          16866: control systems that no one has solved very well yet.
        !          16867: 
        !          16868: If you rename a registered file, you need to rename its master along
        !          16869: with it (the function @code{vc-rename-file} does this automatically).
        !          16870: If you are using SCCS, you must also update the records of the snapshot,
        !          16871: to mention the file by its new name (@code{vc-rename-file} does this,
        !          16872: too).  This makes the snapshot remain valid for retrieval, but it does
        !          16873: not solve all problems.
        !          16874: 
        !          16875: For example, some of the files in the program probably refer to others
        !          16876: by name.  At the very least, the makefile probably mentions the file
        !          16877: that you renamed.  If you retrieve an old snapshot, the renamed file
        !          16878: is retrieved under its new name, which is not the name that the makefile
        !          16879: expects.  So the program won't really work.
        !          16880: 
        !          16881: If you use snapshots, don't rename either work files or master files
        !          16882: except by means of @code{vc-rename-file}.  It knows how to update
        !          16883: snapshots so that you can still retrieve them.  An old snapshot that
        !          16884: refers to a master file that no longer exists under the recorded name is
        !          16885: invalid; VC can no longer retrieve it.  It would be beyond the scope of this
        !          16886: manual to explain enough about RCS and SCCS to teach the reader how to
        !          16887: update the snapshots by hand.
        !          16888: 
        !          16889: @node Version Headers
        !          16890: @subsection Inserting Version Control Headers
        !          16891: 
        !          16892:    Sometimes it is convenient to put version identification strings
        !          16893: directly into working files.  Certain special strings called
        !          16894: @dfn{version headers} are replaced in each successive version by the
        !          16895: number of that version.
        !          16896: 
        !          16897: @kindex C-x v h @r{(V19)}
        !          16898: @findex vc-insert-headers @r{(V19)}
        !          16899:   You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
        !          16900: insert a suitable header string.
        !          16901: 
        !          16902: @table @kbd
        !          16903: @item C-x v h
        !          16904: Insert headers in a file for use with your version-control system.
        !          16905: @end table
        !          16906: 
        !          16907: @vindex vc-header-string @r{(V19)}
        !          16908: @c ??? Currently the name is vc-header-strings
        !          16909: The default header string is @samp{$ld$} for RCS and @samp{%W%} for
        !          16910: SCCS.  You can specify other headers to insert by setting the variable
        !          16911: @code{vc-header-string}.  Its value (if non-@code{nil}) should be the
        !          16912: string to be inserted.  You can also specify a list of strings; then
        !          16913: each string in the list is inserted as a separate header on a line of
        !          16914: its own.  (It is often important to use ``superfluous'' backslashes when
        !          16915: writing a Lisp string constant for this use, to prevent the string in
        !          16916: the constant from being interpreted as a header itself if the Emacs Lisp
        !          16917: file containing it is maintained with version control.)
        !          16918: 
        !          16919: @vindex vc-comment-alist @r{(V19)}
        !          16920: Each header is inserted surrounded by tabs, inside comment delimiters,
        !          16921: on a new line at the start of the buffer.  Normally the ordinary comment
        !          16922: start and comment end strings of the current mode are used, but for
        !          16923: certain modes, there are special comment delimiters for this purpose;
        !          16924: the variable @code{vc-comment-alist} specifies them.  Each element of
        !          16925: this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
        !          16926: 
        !          16927: @vindex vc-static-header-alist @r{(V19)}
        !          16928: @code{vc-static-header-alist} is consulted to add further strings based
        !          16929: on the name of the buffer.  Its value should be a list of
        !          16930: dotted pairs; the @sc{car} of each pair is a regular expression that
        !          16931: should match the buffer name, and the @sc{cdr} is the format to use on
        !          16932: each header.  A string is inserted for each file name pattern that
        !          16933: matches the buffer name, and for each header taken from
        !          16934: @code{vc-header-string}.  The default value for
        !          16935: @code{vc-static-header-alist} is:
        !          16936: 
        !          16937: @example
        !          16938: @group
        !          16939: (("\\.c$" .
        !          16940:   "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
        !          16941: #endif /* lint */\n"))
        !          16942: @end group
        !          16943: @end example
        !          16944: 
        !          16945: @noindent
        !          16946: which specifies insertion of a string of this form:
        !          16947: 
        !          16948: @example
        !          16949: @group
        !          16950: 
        !          16951: #ifndef lint
        !          16952: static char vcid[] = "@var{header-string}";
        !          16953: #endif /* lint */
        !          16954: @end group
        !          16955: @end example
        !          16956: 
        !          16957: @node Emerge
        !          16958: @section Emerge
        !          16959: @cindex Emerge (V19)
        !          16960: @cindex merging files (V19)
        !          16961: 
        !          16962: It's not unusual for programmers to get their signals crossed and modify
        !          16963: the same program in two different directions.  To recover from this
        !          16964: confusion, you need to merge the two versions.  Emerge makes this
        !          16965: easier.
        !          16966: 
        !          16967: @menu
        !          16968: * Overview of Emerge::
        !          16969: * Submodes of Emerge::
        !          16970: * State of Difference::
        !          16971: * Merge Commands::
        !          16972: * Exiting Emerge::
        !          16973: * Combining in Emerge::
        !          16974: * Fine Points of Emerge::
        !          16975: @end menu
        !          16976: 
        !          16977: @node Overview of Emerge
        !          16978: @subsection Overview of Emerge
        !          16979: 
        !          16980: To start Emerge, run one of these four commands:
        !          16981: 
        !          16982: @table @kbd
        !          16983: @item M-x emerge-files
        !          16984: @findex emerge-files @r{(V19)}
        !          16985: Merge two specified files.
        !          16986: 
        !          16987: @item M-x emerge-files-with-ancestor
        !          16988: @findex emerge-files-with-ancestor @r{(V19)}
        !          16989: Merge two specified files, with reference to a common ancestor.
        !          16990: 
        !          16991: @item M-x emerge-buffers
        !          16992: @findex emerge-buffers @r{(V19)}
        !          16993: Merge two buffers (the currently accessible portions).
        !          16994: 
        !          16995: @item M-x emerge-buffers-with-ancestor
        !          16996: @findex emerge-buffers-with-ancestor @r{(V19)}
        !          16997: Merge two buffers (the currently accessible portions) with reference to a
        !          16998: common ancestor in another buffer.
        !          16999: @end table
        !          17000: 
        !          17001: @cindex merge buffer (Emerge)
        !          17002: @cindex A and B buffers (Emerge)
        !          17003: The Emerge commands compare two texts, and display the results in three
        !          17004: buffers: one for each input text (the @dfn{A buffer} and the @dfn{B
        !          17005: buffer}), and one (the @dfn{merge buffer}) where merging takes place.
        !          17006: The merge buffer does not show just the differences.  Rather, it shows
        !          17007: you the full text, but wherever the input texts differ, you can choose
        !          17008: which one of them to include in the merge buffer.
        !          17009: 
        !          17010: If a common ancestor version is available, from which the two texts to
        !          17011: be merged were both derived, Emerge can use it to guess which
        !          17012: alternative is right.  Wherever one current version agrees with the
        !          17013: ancestor, Emerge presumes that the other current version is a deliberate
        !          17014: change which should be kept in the merged version.  Use the
        !          17015: ``with-ancestor'' commands if you want to specify a common ancestor
        !          17016: text.  These commands read three file or buffer names---variant A,
        !          17017: variant B, and the common ancestor.
        !          17018: 
        !          17019: After the comparison is done and the buffers are prepared, the actual
        !          17020: merging starts.  You control the merging interactively by editing the
        !          17021: merge buffer.  The merge buffer shows you a full merged text, not just
        !          17022: differences.  For each point where the input texts differ, you can
        !          17023: choose which one of them to include in the merge buffer.
        !          17024: 
        !          17025: The merge buffer has a special major mode, Emerge mode, with commands
        !          17026: for making these choices.  But you can also edit the buffer with
        !          17027: ordinary Emacs commands.
        !          17028: 
        !          17029: At any given time, the attention of Emerge is focused on one particular
        !          17030: difference, called the @dfn{selected} difference.  This difference is
        !          17031: marked off in the three buffers by 
        !          17032: 
        !          17033: @example
        !          17034: vvvvvvvvvvvvvvvvvvvv
        !          17035: @end example
        !          17036: 
        !          17037: @noindent
        !          17038: above and
        !          17039: 
        !          17040: @example
        !          17041: ^^^^^^^^^^^^^^^^^^^^
        !          17042: @end example
        !          17043: 
        !          17044: @noindent
        !          17045: below.  Emerge numbers all the differences sequentially and the mode
        !          17046: line always shows the number of the selected difference.
        !          17047: 
        !          17048: Normally, the merge buffer starts out with the A version of the text.
        !          17049: But when the A version of a part of the buffer agrees with the common
        !          17050: ancestor, then the B version is preferred for that part.
        !          17051: 
        !          17052: Normally, Emerge stores the merged output in place of the first input
        !          17053: text (the A file or buffer).  If you give a prefix argument to
        !          17054: @code{emerge-files} or @code{emerge-files-with-ancestor}, it reads the
        !          17055: name of the output file using the minibuffer.  (This is the last file
        !          17056: name those commands read.)
        !          17057: 
        !          17058: If you abort Emerge with @kbd{C-u q}, the output is not saved.
        !          17059: 
        !          17060: @node Submodes of Emerge
        !          17061: @subsection Submodes of Emerge
        !          17062: 
        !          17063: You can choose between two modes for giving merge commands: Fast mode
        !          17064: and Edit mode.  In Fast mode, basic Emerge commands are single
        !          17065: characters, but ordinary Emacs commands are disabled.  This is
        !          17066: convenient if you use only Emerge commands.
        !          17067: 
        !          17068: In Edit mode, all Emerge commands start with the prefix character
        !          17069: @kbd{C-c}, and the normal Emacs commands are also available.  This
        !          17070: allows editing the merge buffer, but slows down Emerge operations.
        !          17071: 
        !          17072: Use @kbd{e} to switch to Edit mode, and @kbd{f} to switch to Fast mode.
        !          17073: The mode line indicates Edit and Fast modes with @samp{E} and @samp{F}.
        !          17074: 
        !          17075: Emerge has two additional submodes that affect how particular merge
        !          17076: commands work: Auto Advance mode and Skip Prefers mode.
        !          17077: 
        !          17078: If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
        !          17079: advance to the next difference.  This lets you go through the merge
        !          17080: faster doing ordinary things.  The mode line indicates Auto Advance mode
        !          17081: with @samp{A}.
        !          17082: 
        !          17083: If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands skip
        !          17084: over differences in states prefer-A and prefer-B.  Thus you will only
        !          17085: see differences for which neither version is presumed ``correct''.  The
        !          17086: mode line indicates Skip Prefers mode with @samp{S}.
        !          17087: 
        !          17088: @findex emerge-auto-advance-mode @r{(V19)}
        !          17089: @findex emerge-skip-prefers-mode @r{(V19)}
        !          17090: Use the command @code{emerge-auto-advance-mode} to set or clear Auto
        !          17091: Advance mode.  Use @code{emerge-skip-prefers-mode} to set or clear Skip
        !          17092: Prefers mode.  A positive argument turns the mode on, a nonpositive
        !          17093: argument turns it off, and no argument toggles it.
        !          17094: 
        !          17095: @node State of Difference
        !          17096: @subsection State of a Difference
        !          17097: 
        !          17098: In the merge buffer, a difference is marked
        !          17099: @samp{vvvvvvvvvvvvvvvvvvvv} above and @samp{^^^^^^^^^^^^^^^^^^^^}
        !          17100: below.  Such a difference can have one of seven states:
        !          17101: 
        !          17102: @table @asis
        !          17103: @item A
        !          17104: The difference is showing the A version.  The @kbd{a} command always
        !          17105: produces this state; the mode line indicates it with @samp{A}.
        !          17106: 
        !          17107: @item B
        !          17108: The difference is showing the B version.  The @kbd{b} command always
        !          17109: produces this state; the mode line indicates it with @samp{B}.
        !          17110: 
        !          17111: @item default-A
        !          17112: @itemx default-B
        !          17113: The difference is showing the A or the B state by default, because you
        !          17114: haven't made a choice.  All differences start in the default-A state
        !          17115: (and thus the merge buffer is a copy of the A buffer), except those for
        !          17116: which one alternative is ``preferred'' (see below).
        !          17117: 
        !          17118: When you select a difference, its state changes from default-A or
        !          17119: default-B to plain A or B.  Thus, the selected difference never has
        !          17120: state default-A or default-B, and these states are never displayed in
        !          17121: the mode line.
        !          17122: 
        !          17123: The command @kbd{d a} chooses default-A as the default state, and @kbd{d
        !          17124: b} chooses default-B.  This chosen default applies to all differences
        !          17125: which you haven't selected and for which no alternative is preferred.
        !          17126: If you are moving through the merge sequentially, the differences you
        !          17127: haven't selected are those following the selected one.  Thus, while
        !          17128: moving sequentially, you can effectively make the A version the default
        !          17129: for some sections of the merge buffer and the B version the default for
        !          17130: others by using @kbd{d a} and @kbd{d b} at the end of each section.
        !          17131: 
        !          17132: @item prefer-A
        !          17133: @itemx prefer-B
        !          17134: The difference is showing the A or B state because it is
        !          17135: @dfn{preferred}.  This means that you haven't made an explicit choice,
        !          17136: but one alternative seems likely to be right because the other
        !          17137: alternative agrees with the common ancestor.  Thus, where the A buffer
        !          17138: agrees with the common ancestor, the B version is preferred, because
        !          17139: chances are it is the one that was actually changed.
        !          17140: 
        !          17141: These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
        !          17142: 
        !          17143: @item combined
        !          17144: The difference is showing a combination of the A and B states, as a
        !          17145: result of the @kbd{x c} or @kbd{x C} commands.
        !          17146: 
        !          17147: Once a difference is in this state, the @kbd{a} and @kbd{b} commands
        !          17148: don't do anything to it unless you give them a prefix argument.
        !          17149: 
        !          17150: The mode line displays this state as @samp{comb}.
        !          17151: @end table
        !          17152: 
        !          17153: @node Merge Commands
        !          17154: @subsection Merge Commands
        !          17155: 
        !          17156: Here are the Merge commands for Fast mode; in Edit mode, precede these with
        !          17157: @kbd{C-c} and turn all the letters into control characters.
        !          17158: 
        !          17159: @table @kbd
        !          17160: @item p
        !          17161: Select the previous difference.
        !          17162: 
        !          17163: @item n
        !          17164: Select the next difference.
        !          17165: 
        !          17166: @item a
        !          17167: Choose the A version of this difference.
        !          17168: 
        !          17169: @item b
        !          17170: Choose the B version of this difference.
        !          17171: 
        !          17172: @item j
        !          17173: Select a particular difference; specify the sequence number of that
        !          17174: difference as a prefix argument.
        !          17175: 
        !          17176: @item M-x emerge-select-difference
        !          17177: @c ??? This isn't true yet.
        !          17178: Select the run of differences containing the current location.  You can
        !          17179: use this command in the merge buffer or in the A or B buffer.
        !          17180: 
        !          17181: @item q
        !          17182: Quit---finish the merge.  With an argument, abort the merge.
        !          17183: 
        !          17184: @item f
        !          17185: Go into fast mode.
        !          17186: 
        !          17187: @item e
        !          17188: Go into edit mode.
        !          17189: 
        !          17190: @item l
        !          17191: Recenter (like @kbd{C-l}) all three windows.
        !          17192: 
        !          17193: @item - 
        !          17194: Specify part of a prefix numeric argument.
        !          17195: @c Don't use itemx here, it is confusing in printed output!
        !          17196: @itemx @var{digit}
        !          17197: Also specify part of a prefix numeric argument.
        !          17198: 
        !          17199: @item d a
        !          17200: Choose the A version as the default from here down in
        !          17201: the merge buffer.
        !          17202: 
        !          17203: @item d b
        !          17204: Choose the B version as the default from here down in
        !          17205: the merge buffer.
        !          17206: 
        !          17207: @item c a
        !          17208: Copy the A version of this difference into the kill ring.
        !          17209: 
        !          17210: @item c b
        !          17211: Copy the B version of this difference into the kill ring.
        !          17212: 
        !          17213: @item i a
        !          17214: Insert the A version of this difference at the point.
        !          17215: 
        !          17216: @item i b
        !          17217: Insert the B version of this difference at the point.
        !          17218: 
        !          17219: @item m
        !          17220: Put the point and mark around the difference region.
        !          17221: 
        !          17222: @item ^
        !          17223: Scroll all three windows down (like @kbd{M-v}).
        !          17224: 
        !          17225: @item v
        !          17226: Scroll all three windows up (like @kbd{C-v}).
        !          17227: 
        !          17228: @item <
        !          17229: Scroll all three windows left (like @kbd{C-x <}).
        !          17230: 
        !          17231: @item >
        !          17232: Scroll all three windows right (like @kbd{C-x >}).
        !          17233: 
        !          17234: @item |
        !          17235: Reset horizontal scroll on all three windows.
        !          17236: 
        !          17237: @item x 1
        !          17238: Shrink the merge window to one line.  (Use @kbd{C-u l} to restore it
        !          17239: to full size.)
        !          17240: 
        !          17241: @item x c
        !          17242: Combine the two versions of this difference.
        !          17243: 
        !          17244: @item x f
        !          17245: Show the files/buffers Emerge is operating on in Help window.
        !          17246: (Use @kbd{C-u l} to restore windows.)
        !          17247: 
        !          17248: @item x j
        !          17249: Join this difference with the following one.
        !          17250: (@kbd{C-u x j} joins this difference with the previous one.)
        !          17251: 
        !          17252: @item x s
        !          17253: Split this difference into two differences.  Before you use this
        !          17254: command, position point in each of the three buffers to the place where
        !          17255: you want to split the difference.
        !          17256: 
        !          17257: @item x t
        !          17258: Trim identical lines off top and bottom of the difference.
        !          17259: Such lines occur when the A and B versions are
        !          17260: identical but differ from the ancestor version.
        !          17261: @end table
        !          17262: 
        !          17263: @node Exiting Emerge
        !          17264: @subsection Exiting Emerge
        !          17265: 
        !          17266: The @kbd{q} (@code{emerge-quit}) command finishes the merge, storing the
        !          17267: results into the output file.  It restores the A and B buffers to their
        !          17268: proper contents, or kills them if they were created by Emerge.  It also
        !          17269: disables the Emerge commands in the merge buffer, since executing them
        !          17270: later could damage the contents of the various buffers.
        !          17271: 
        !          17272: @kbd{C-u q} aborts the merge.  Aborting means that Emerge does not write
        !          17273: the output file.
        !          17274: 
        !          17275: If Emerge was called from another Lisp program, then its return value
        !          17276: is @code{t} or @code{nil} to indicate success or failure.
        !          17277: 
        !          17278: @node Combining in Emerge
        !          17279: @subsection Combining the Two Versions
        !          17280: 
        !          17281: Sometimes you want to keep @emph{both} alternatives for a particular 
        !          17282: locus.  To do this, use @kbd{x c}, which edits the merge buffer like this:
        !          17283: 
        !          17284: @example
        !          17285: @group
        !          17286: #ifdef NEW
        !          17287: @var{version from A file}
        !          17288: #else /* NEW */
        !          17289: @var{version from B file}
        !          17290: #endif /* NEW */
        !          17291: @end group
        !          17292: @end example
        !          17293: 
        !          17294: @vindex emerge-combine-template @r{(V19)}
        !          17295: While this example shows C preprocessor conditionals delimiting the two
        !          17296: alternative versions, you can specify the strings you want by setting
        !          17297: the variable @code{emerge-combine-template} to a list of three strings.
        !          17298: The default setting, which produces the results shown above, looks like this:
        !          17299: 
        !          17300: @example
        !          17301: @group
        !          17302: ("#ifdef NEW\n"
        !          17303:  "#else /* NEW */\n"
        !          17304:  "#endif /* NEW */\n")
        !          17305: @end group
        !          17306: @end example
        !          17307: @c ??? This is not how it currently works;
        !          17308: @c ??? emerge.el needs to be changed.
        !          17309: 
        !          17310: @c ??? Must change the mechanism that disables saving during emerge
        !          17311: @c ??? to use a write-file-function instead.
        !          17312: 
        !          17313: @c ??? Emerge should use flag strings that start with # for C programs
        !          17314: @c ??? and with ; for Lisp programs.
        !          17315: 
        !          17316: @node Fine Points of Emerge
        !          17317: @subsection Fine Points of Emerge
        !          17318: 
        !          17319: You can have any number of merges going at once---just don't use any
        !          17320: one buffer as input to more than one merge at once, since that will
        !          17321: cause the read-only/modified/auto-save status save-and-restore to
        !          17322: screw up.
        !          17323: 
        !          17324: Starting Emerge can take a long time because it needs to compare the
        !          17325: files.  Emacs can't do anything else until @code{diff} finishes.  Perhaps in
        !          17326: the future someone will change Emerge to do the comparison in the
        !          17327: background when the input files are large---then you could keep on doing
        !          17328: other things with Emacs until Emerge gets ready to accept commands.
        !          17329: 
        !          17330: @ignore
        !          17331: @c ??? This name hasn't been changed yet.
        !          17332: @vindex emerge-ok-lines-regexp @r{(V19)}
        !          17333: Emerge tests each of the lines that differ against the regular
        !          17334: expression @code{emerge-ok-lines-regexp}.  If a line fails to fit the
        !          17335: pattern, then Emerge displays a warning instead of displaying the merge
        !          17336: buffer.  After you get the warning, you must switch to the merge buffer
        !          17337: and either continue the merge or abort it.
        !          17338: @end ignore
        !          17339: 
        !          17340: @vindex emerge-startup-hook @r{(V19)}
        !          17341: After the merge has been set up, Emerge runs the hooks in
        !          17342: @code{emerge-startup-hook}.
        !          17343: 
        !          17344: During the merge, you musn't try to edit the A and B buffers yourself.
        !          17345: Emerge modifies them temporarily, but ultimately puts them back the way
        !          17346: they were.
        !          17347: 
        !          17348: @node Debuggers
        !          17349: @section Running Debuggers Under Emacs
        !          17350: @cindex debuggers
        !          17351: @cindex GDB
        !          17352: @cindex DBX
        !          17353: @cindex SDB
        !          17354: 
        !          17355: @c Do you believe in GUD?
        !          17356: The GUD (Grand Unified Debugger) library provides an interface to various
        !          17357: symbolic debuggers from within Emacs.  We recommend the debugger GDB,
        !          17358: which is free software, but you can also run DBX or SDB if you have them.
        !          17359: 
        !          17360: @menu
        !          17361: * Starting GUD::       How to start a debugger subprocess.
        !          17362: * Debugger Operation:: Connection between the debugger and source buffers.
        !          17363: * Commands of GUD::    Keybindings for common commands.
        !          17364: * GUD Customization::  Defining your own commands for GUD.
        !          17365: @end menu
        !          17366: 
        !          17367: @node Starting GUD
        !          17368: @subsection Starting GUD
        !          17369: 
        !          17370: There are three commands for starting a debugger.  Each corresponds to a
        !          17371: particular debugger program.
        !          17372: 
        !          17373: @table @kbd
        !          17374: @item M-x gdb @key{RET} @var{file} @key{RET}
        !          17375: @itemx M-x dbx @key{RET} @var{file} @key{RET}
        !          17376: @findex gdb @r{(V19)}
        !          17377: @findex dbx @r{(V19)}
        !          17378: Run GDB or DBX in a subprocess of Emacs.  Both of these commands select
        !          17379: the buffer used for input and output to the debugger.
        !          17380: 
        !          17381: @item M-x sdb @key{RET} @var{file} @key{RET}
        !          17382: @findex sdb @r{(V19)}
        !          17383: Run SDB in a subprocess of Emacs.  SDB's messages do not mention file
        !          17384: names, so the Emacs interface to SDB depends on having a tags table
        !          17385: (@pxref{Tags}) to find which file each function is in.  If you have not
        !          17386: visited a tags table or the tags table doesn't list one of the
        !          17387: functions, you get a message saying @samp{The sdb support requires a
        !          17388: valid tags table to work}.  If this happens, generate a valid tags table
        !          17389: in the working directory and try again.
        !          17390: @end table
        !          17391: 
        !          17392: You can only run one debugger process at a time.
        !          17393: 
        !          17394: @node Debugger Operation
        !          17395: @subsection Debugger Operation
        !          17396: 
        !          17397: When you run a debugger with GUD, the debugger displays source files
        !          17398: via Emacs---Emacs finds the source file and moves point to the line
        !          17399: where the program is executing.  An arrow (@samp{=>}) indicates the
        !          17400: current execution line, and it stays put even if you move the cursor.
        !          17401: 
        !          17402: You can start editing the file at any time.  The arrow is not part of
        !          17403: the file's text; it appears only on the screen.  If you do modify a
        !          17404: source file, keep in mind that inserting or deleting lines will throw
        !          17405: off the arrow's positioning; GUD has no way of figuring out which line
        !          17406: corresponded before your changes to the line number in a debugger
        !          17407: message.  Also, you'll typically have to recompile and restart the
        !          17408: program for your changes to be reflected in the debugger's tables.
        !          17409: 
        !          17410: If you wish, you can control your debugger process entirely through the
        !          17411: debugger buffer, which uses a variant of Shell mode.  All the usual
        !          17412: commands for your debugger are available, and you can use the Shell mode
        !          17413: history commands to repeat them.
        !          17414: 
        !          17415: @node Commands of GUD
        !          17416: @subsection Commands of GUD
        !          17417: 
        !          17418: GUD provides a command available in all buffers for setting
        !          17419: breakpoints.  This command is defined globally because you need to use
        !          17420: it in the source files' buffers.
        !          17421: 
        !          17422: @table @kbd
        !          17423: @item C-x @key{SPC}
        !          17424: @kindex C-x @key{SPC} @r{(V19)}
        !          17425: Set a breakpoint on the line that point is on.
        !          17426: @end table
        !          17427: 
        !          17428: The debugger buffer has a number of keybindings for invoking common
        !          17429: debugging commands quickly:
        !          17430: 
        !          17431: @table @kbd
        !          17432: @item C-c C-l
        !          17433: @kindex C-c C-l @r{(GUD in V19)}
        !          17434: @findex gud-refresh @r{(V19)}
        !          17435: Display in another window the last line referred to in the GUD
        !          17436: buffer (that is, the line indicated in the last location message).
        !          17437: This runs the command @code{gud-refresh}.
        !          17438: 
        !          17439: @item C-c C-s
        !          17440: @kindex C-c C-s @r{(GUD in V19)}
        !          17441: @findex gud-step @r{(V19)}
        !          17442: Execute a single line of code (@code{gud-step}).  If the code contains
        !          17443: a function call, execution stops after entering the called function.
        !          17444: 
        !          17445: @item C-c C-n
        !          17446: @kindex C-c C-n @r{(GUD in V19)}
        !          17447: @findex gud-next @r{(V19)}
        !          17448: Execute a single line of code, stepping across entire function calls
        !          17449: at full speed (@code{gud-next}).
        !          17450: 
        !          17451: @item C-c C-i
        !          17452: @kindex C-c C-i @r{(GUD in V19)}
        !          17453: @findex gud-stepi @r{(V19)}
        !          17454: Execute a single machine instruction (@code{gud-stepi}).
        !          17455: 
        !          17456: @item C-c C-c
        !          17457: @kindex C-c C-c @r{(GUD in V19)}
        !          17458: @findex gud-cont @r{(V19)}
        !          17459: Continue execution until the next breakpoint, or other event that would
        !          17460: normally stop the program (@code{gud-cont}).
        !          17461: @end table
        !          17462: 
        !          17463: The above commands are common to all supported debuggers.  If you are
        !          17464: using GDB or (some versions of) DBX, these additional commands are available:
        !          17465: 
        !          17466: @table @kbd
        !          17467: @item C-c <
        !          17468: @kindex C-c < @r{(GUD in V19)}
        !          17469: @findex gud-up @r{(V19)}
        !          17470: Select the next enclosing stack frame (@code{gud-up}).  This is
        !          17471: equivalent to the @samp{up} command.
        !          17472: 
        !          17473: @item C-c >
        !          17474: @kindex C-c > @r{(GUD in V19)}
        !          17475: @findex gud-down @r{(V19)}
        !          17476: Select the next inner stack frame (@code{gud-down}).  This is
        !          17477: equivalent to the @samp{down} command.
        !          17478: @end table
        !          17479: 
        !          17480: If you are using GDB, two additional keybindings are available:
        !          17481: 
        !          17482: @table @kbd
        !          17483: @item C-c C-f
        !          17484: @kindex C-c C-f @r{(GUD in V19)}
        !          17485: @findex gud-finish @r{(V19)}
        !          17486: Run the program until the selected stack frame returns (or until it
        !          17487: stops for some other reason).
        !          17488: 
        !          17489: @item @key{TAB}
        !          17490: Complete the symbol in the buffer before point, using the set of all
        !          17491: symbols known to GDB.
        !          17492: @end table
        !          17493: 
        !          17494: These commands interpret a prefix argument as a repeat count, when that
        !          17495: makes sense.
        !          17496: 
        !          17497: After each command that changes the program counter, GUD displays the
        !          17498: new current source line, and updates the location of the arrow.
        !          17499: 
        !          17500: @node GUD Customization
        !          17501: @subsection GUD Customization
        !          17502: 
        !          17503: @vindex gdb-mode-hook
        !          17504: @vindex dbx-mode-hook
        !          17505: @vindex sdb-mode-hook
        !          17506: On startup, GUD executes one of the following hooks:
        !          17507: @code{gdb-mode-hook}, if you are using GDB; @code{dbx-mode-hook}, if you
        !          17508: are using DBX; and @code{sdb-mode-hook}, if you are using SDB.  You can
        !          17509: use these hooks to define custom keybindings for the debugger
        !          17510: interaction buffer.
        !          17511: 
        !          17512: Here is a convenient way to define a command that sends a particular
        !          17513: command string to the debugger, and set up a key binding for it in the
        !          17514: debugger interaction buffer:
        !          17515: 
        !          17516: @findex gud-def @r{(V19)}
        !          17517: @example
        !          17518: (gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring})
        !          17519: @end example
        !          17520: 
        !          17521:   This defines a command named @var{function} which sends
        !          17522: @var{cmdstring} to the debugger process, with documentation string
        !          17523: @var{docstring}, and binds it to @var{binding} in the debugger buffer's
        !          17524: mode.  (If @var{binding} is @code{nil}, this defines the command but
        !          17525: does not make a binding for it; you can make a binding explicitly,
        !          17526: perhaps using one of the above hooks.)
        !          17527: 
        !          17528:    Commands defined with @code{gud-def} handle prefix arguments by
        !          17529: passing them to the debugger, appended to end of @var{cmdstring} with a
        !          17530: space in between.  (This use of prefix arguments works with GDB and DBX,
        !          17531: but not with SDB.)
        !          17532: 
        !          17533: You can also set up commands that you can send to the debugger while in
        !          17534: another buffer, such as a source file.  Set the variable
        !          17535: @code{gud-commands} to a list of strings containing debugger commands
        !          17536: you might want to send.
        !          17537: 
        !          17538: @table @kbd
        !          17539: @item C-x &
        !          17540: @kindex C-x & @r{(GUD in V19)}
        !          17541: @findex send-gud-command @r{(V19)}
        !          17542: Send a custom command to the debugger process
        !          17543: (@code{send-gud-command}).  Normally, send the @sc{car} of the
        !          17544: @code{gud-commands} list; a prefix argument specifies which element of
        !          17545: that list to use (counting from 0).
        !          17546: 
        !          17547: If the string contains @samp{%s}, @kbd{C-x &} substitutes a numeric
        !          17548: value found in the buffer at or near point.  It looks for decimal,
        !          17549: octal, or hexadecimal numbers, with @samp{0x} allowed.  This lets you
        !          17550: define commands to chase pointers whose numeric values have been
        !          17551: displayed.
        !          17552: @end table
        !          17553: 
        !          17554: @node Other New Modes
        !          17555: @section Other New Modes
        !          17556: 
        !          17557: There is now a Perl mode for editing Perl programs and an Icon mode
        !          17558: for editing Icon programs.
        !          17559: 
        !          17560: @cindex C++ mode @r{(V19)}
        !          17561: @findex fill-c++-comment @r{(V19)}
        !          17562: C++ mode is like C mode, except that it understands C++ comment syntax
        !          17563: and certain other differences between C and C++.  It also has a command
        !          17564: @code{fill-c++-comment} which fills a paragraph made of comment lines.
        !          17565: The command @code{comment-region} is useful in C++ mode for commenting
        !          17566: out several consecutive lines, or removing the commenting out of such
        !          17567: lines.
        !          17568: 
        !          17569: @cindex WordStar mode @r{(V19)}
        !          17570: WordStar emulation is available---type @kbd{M-x wordstar-mode}.
        !          17571: For more information, type @kbd{C-h f wordstar-mode @key{RET}}.
        !          17572: 
        !          17573: @cindex Buffer Menu mode @r{(V19)}
        !          17574: The command @kbd{C-o} in Buffer Menu mode now displays the current
        !          17575: line's buffer in another window but does not select it.  This is like
        !          17576: the existing command @kbd{o} which selects the current line's buffer in
        !          17577: another window.
        !          17578: 
        !          17579: @menu
        !          17580: * Asm Mode::           A major mode for editing assembler files.
        !          17581: * Edebug Mode::                A new Lisp debugger.
        !          17582: * Editing Binary Files::Hexl mode lets you edit a binary file as numbers.
        !          17583: @end menu
        !          17584: 
        !          17585: @node Asm Mode
        !          17586: @subsection Asm Mode
        !          17587: 
        !          17588: @cindex Asm mode @r{(V19)}
        !          17589: Asm mode is a new major mode for editing files of assembler code.
        !          17590: It defines these commands:
        !          17591: 
        !          17592: @table @kbd
        !          17593: @item @key{TAB}
        !          17594: @code{tab-to-tab-stop}.
        !          17595: @item @key{LFD}
        !          17596: Insert a newline and then indent using @code{tab-to-tab-stop}.
        !          17597: @item :
        !          17598: Insert a colon and then remove the indentation from before the label
        !          17599: preceding colon.  Then do @code{tab-to-tab-stop}.
        !          17600: @item ;
        !          17601: Insert or align a comment.
        !          17602: @end table
        !          17603: 
        !          17604: @node Edebug Mode
        !          17605: @subsection Edebug Mode
        !          17606: @cindex Edebug mode @r{(V19)}
        !          17607: 
        !          17608: Edebug is a new source-level debugger for Emacs Lisp programs.
        !          17609: 
        !          17610: @findex edebug-defun @r{(V19)}
        !          17611: To use Edebug, use the command @kbd{M-x edebug-defun} to ``evaluate'' a
        !          17612: function definition in an Emacs Lisp file.  We put ``evaluate'' in
        !          17613: quotation marks because it doesn't just evaluate the function, it also
        !          17614: inserts additional information to support source-level debugging.
        !          17615: 
        !          17616: You must also do this:
        !          17617: 
        !          17618: @example
        !          17619: (setq debugger 'edebug-debug)
        !          17620: @end example
        !          17621: 
        !          17622: @noindent
        !          17623: to cause errors and single-stepping to use Edebug instead of the usual
        !          17624: Emacs Lisp debugger.
        !          17625: 
        !          17626: @c ???  Need xref to Edebug manual
        !          17627: For more information, see @cite{The Emacs Extensions Manual}, which
        !          17628: should be included in the Emacs 19 distribution.
        !          17629: 
        !          17630: @node Editing Binary Files
        !          17631: @subsection Editing Binary Files
        !          17632: 
        !          17633: @cindex Hexl mode @r{(V19)}
        !          17634: @cindex editing binary files @r{(V19)}
        !          17635: There is a new major mode for editing binary files: Hexl mode.  To use
        !          17636: it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit the
        !          17637: file.  This command converts the file's contents to hexadecimal and lets
        !          17638: you edit the translation.  When you save the file, it is converted
        !          17639: automatically back to binary.
        !          17640: 
        !          17641: You can also use @kbd{M-x hexl-mode} to translate an existing buffer
        !          17642: into hex.  This is useful if you visit a file normally and discover it
        !          17643: is a binary file.
        !          17644: 
        !          17645: Hexl mode has a few other commands:
        !          17646: 
        !          17647: @c I don't think individual index entries for these commands are useful--RMS.
        !          17648: @table @kbd
        !          17649: @item C-M-d
        !          17650: Insert a byte with a code typed in decimal.
        !          17651: 
        !          17652: @item C-M-o
        !          17653: Insert a byte with a code typed in octal.
        !          17654: 
        !          17655: @item C-M-x
        !          17656: Insert a byte with a code typed in hex.
        !          17657: 
        !          17658: @item C-x [
        !          17659: Move to the beginning of a 1k-byte ``page''.
        !          17660: 
        !          17661: @item C-x ]
        !          17662: Move to the end of a 1k-byte ``page''.
        !          17663: 
        !          17664: @item M-g
        !          17665: Move to an address specified in hex.
        !          17666: 
        !          17667: @item M-j
        !          17668: Move to an address specified in decimal.
        !          17669: 
        !          17670: @item C-c C-c
        !          17671: Leave Hexl mode, going back to the major mode this buffer had before you
        !          17672: invoked @code{hexl-mode}.
        !          17673: @end table
        !          17674: 
        !          17675: @node Key Sequence Changes
        !          17676: @section Changes in Key Sequences
        !          17677: @cindex function keys (V19)
        !          17678: @cindex mouse buttons (V19)
        !          17679: @cindex key sequence changes (V19)
        !          17680: 
        !          17681: In Emacs 18, a key sequence was a sequence of characters, which
        !          17682: represented keyboard input.
        !          17683: 
        !          17684: In Emacs 19, you can still use a sequence of characters as a key
        !          17685: sequence, but you aren't limited to characters.  You can also use Lisp
        !          17686: symbols which represent terminal function keys or mouse buttons.  If the
        !          17687: function key has a word as its label, then that word is also the name of
        !          17688: the symbol which represents the function key.  Other function keys
        !          17689: are assigned Lisp names as follows:
        !          17690: 
        !          17691: @table @asis
        !          17692: @item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} 
        !          17693: Keypad keys (to the right of the regular keyboard), with names or punctuation
        !          17694: @item @code{kp-0}, @code{kp-1}, @dots{}
        !          17695: Keypad keys with digits
        !          17696: @item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
        !          17697: Keypad PF keys
        !          17698: @item @code{left}, @code{up}, @code{right}, @code{down}
        !          17699: Cursor arrow keys
        !          17700: @end table
        !          17701: 
        !          17702: A key sequence which contains non-characters must be a vector rather
        !          17703: than a string.
        !          17704: 
        !          17705: Thus, to bind function key @samp{f1} to @code{rmail}, write the
        !          17706: following:
        !          17707: 
        !          17708: @example
        !          17709: (global-set-key [f1] 'rmail)
        !          17710: @end example
        !          17711: 
        !          17712: @noindent
        !          17713: (To find the name of a key, type @kbd{C-h k} and then the key.)
        !          17714: 
        !          17715: To bind the right-arrow key to the command @code{forward-char},
        !          17716: you can use this expression:
        !          17717: 
        !          17718: @example
        !          17719: (global-set-key [right] 'forward-char)
        !          17720: @end example
        !          17721: 
        !          17722: @noindent
        !          17723: using the Lisp syntax for a vector containing the symbol @code{right}.
        !          17724: 
        !          17725: And this is how to make @kbd{C-x @key{RIGHTARROW}} move forward a page:
        !          17726: 
        !          17727: @example
        !          17728: (global-set-key [?\C-x right] 'forward-page)
        !          17729: @end example
        !          17730: 
        !          17731: @noindent
        !          17732: where @code{?\C-x} is the Lisp syntax for an integer whose value is the
        !          17733: code for the character @kbd{C-x}.
        !          17734: 
        !          17735: You can use modifier keys such as @key{CTRL}, @key{META} and @key{SHIFT}
        !          17736: with function keys.  To represent these modifiers, prepend the strings
        !          17737: @samp{C-}, @samp{M-} and @samp{S-} to the symbol name.  Thus, here is
        !          17738: how to make @kbd{M-@key{RIGHTARROW}} move forward a word:
        !          17739: 
        !          17740: @example
        !          17741: (global-set-key [M-right] 'forward-word)
        !          17742: @end example
        !          17743: 
        !          17744: Emacs uses symbols to designate mouse buttons, too.
        !          17745: The ordinary mouse events in Emacs are @dfn{click} events; these
        !          17746: happen when you press a button and release it without moving the mouse.
        !          17747: You can also get @dfn{drag} events, when you move the mouse while
        !          17748: holding the button down.  Drag events happen when you finally let go
        !          17749: of the button.
        !          17750:   
        !          17751: The symbols for basic click events are @code{mouse-1} for the leftmost
        !          17752: button, @code{mouse-2} for the next, and so on.  Here is how you can
        !          17753: redefine the second mouse button to split the current window:
        !          17754: 
        !          17755: @findex global-set-key @r{(V19)}
        !          17756: @example
        !          17757: (global-set-key [mouse-2] 'split-window-vertically)
        !          17758: @end example
        !          17759: 
        !          17760: The symbols for drag events are similar, but have the prefix @samp{drag-}
        !          17761: before the word @samp{mouse}.  For example, dragging the left button
        !          17762: generates a @code{drag-mouse-1} event.
        !          17763: 
        !          17764: You can also request events when the mouse button is pressed down.
        !          17765: These events start with @samp{down-} instead of @samp{drag-}.  Such
        !          17766: events are generated only if they have key bindings.  When you get a
        !          17767: button-down event, a corresponding click or drag event will always
        !          17768: follow.
        !          17769: 
        !          17770: The symbols for mouse events also indicate the status of the modifier
        !          17771: keys, with the usual prefixes @samp{C-}, @samp{M-} and @samp{S-}.
        !          17772: These always follow @samp{drag-} or @samp{down-}.
        !          17773: @c ??? This is a change; currently they precede.
        !          17774: 
        !          17775: When mouse events occur in special parts of a frame or window, such as a
        !          17776: mode line or a scroll bar, the event symbol shows nothing special.  The
        !          17777: information about the special part is implicit in other data (the screen
        !          17778: location of the event).  But @code{read-key-sequence} figures out this
        !          17779: aspect of the event, and encodes it with make-believe prefix keys, all
        !          17780: of which are symbols: @code{mode-line}, @code{vertical-line},
        !          17781: @code{horizontal-scrollbar} and @code{vertical-scrollbar}.  Thus, to
        !          17782: define the command for clicking the left button in a mode line, you
        !          17783: could use this key sequence:
        !          17784: 
        !          17785: @example
        !          17786: [mode-line mouse-1]
        !          17787: @end example
        !          17788: 
        !          17789: You are not limited to defining individual function keys or mouse
        !          17790: buttons; these can appear anywhere in a key sequence, just as characters
        !          17791: can.  You can even mix together all three kinds of inputs in one key
        !          17792: sequence---but mixing mouse buttons with keyboard inputs is probably not
        !          17793: convenient for actual use.
        !          17794: 
        !          17795: @node Hook Changes
        !          17796: @section Changes Regarding Hooks
        !          17797: @cindex normal hook (V19)
        !          17798: @cindex hook variable (V19)
        !          17799: 
        !          17800: A @dfn{hook variable} is a variable that exists so that you can store in
        !          17801: it functions for Emacs to call on certain occasions.  (The functions that
        !          17802: you put in hook variables are called @dfn{hook functions}.)  Emacs 19
        !          17803: has a new convention for naming hook variables that indicates more
        !          17804: reliably how to use them.
        !          17805: 
        !          17806: All the variables whose names end in @samp{-hook} are @dfn{normal
        !          17807: hooks}; their values are lists of functions to be called with no
        !          17808: arguments.  You can use @code{add-hook} (see below) to install hook
        !          17809: functions in these hooks.  We have made all Emacs hooks into normal
        !          17810: hooks except when there is some reason this won't work.
        !          17811: 
        !          17812: A few hook-like variables are @dfn{abnormal}---they don't use the normal
        !          17813: convention.  This is either because the user-supplied functions receive
        !          17814: arguments, or because their return values matter.  These variables have
        !          17815: names that end in @samp{-function} (if the value is a single function)
        !          17816: or @samp{-functions} (if the value is a list of functions).
        !          17817: 
        !          17818: Thus, you can always tell from the variable's name precisely how to
        !          17819: install a new hook function in the variable.  If the name indicates a
        !          17820: normal hook, then you also know how to write your hook function.
        !          17821: 
        !          17822: @findex add-hook @r{(V19)}
        !          17823: To add a hook function to a normal hook, use @code{add-hook}.  It takes
        !          17824: care of adding a new hook function to any functions already installed in
        !          17825: a given hook.  It takes two arguments, the hook symbol and the function
        !          17826: to add.  For example,
        !          17827: 
        !          17828: @example
        !          17829: (add-hook 'text-mode-hook 'my-text-hook-function)
        !          17830: @end example
        !          17831: 
        !          17832: @noindent
        !          17833: is how to arrange to call @code{my-text-hook-function} when entering
        !          17834: Text mode or related modes.
        !          17835: @vindex pre-abbrev-expand-hook @r{(V19)}
        !          17836: @vindex kill-buffer-hook @r{(V19)}
        !          17837: Two new hooks are worth noting here.  Expansion of an abbrev
        !          17838: first runs the hook @code{pre-abbrev-expand-hook}.
        !          17839: @code{kill-buffer-hook} now runs whenever a buffer is killed.
        !          17840: @c end antenews
        !          17841: 
        !          17842: @node Manifesto,, Version 19, Top
        !          17843: @unnumbered The GNU Manifesto
        !          17844: 
        !          17845: @b{By Richard M. Stallman, 1986}
        !          17846: 
        !          17847: @unnumberedsec What's GNU?  Gnu's Not Unix!
        !          17848: 
        !          17849: GNU, which stands for Gnu's Not Unix, is the name for the complete
        !          17850: Unix-compatible software system which I am writing so that I can give it
        !          17851: away free to everyone who can use it.  Several other volunteers are helping
        !          17852: me.  Contributions of time, money, programs and equipment are greatly
        !          17853: needed.
        !          17854: 
        !          17855: So far we have an Emacs text editor with Lisp for writing editor commands,
        !          17856: a source level debugger, a yacc-compatible parser generator, a linker, and
        !          17857: around 35 utilities.  A shell (command interpreter) is nearly completed.  A
        !          17858: new portable optimizing C compiler has compiled itself and may be released
        !          17859: this year.  An initial kernel exists but many more features are needed to
        !          17860: emulate Unix.  When the kernel and compiler are finished, it will be
        !          17861: possible to distribute a GNU system suitable for program development.  We
        !          17862: will use @TeX{} as our text formatter, but an nroff is being worked on.  We
        !          17863: will use the free, portable X window system as well.  After this we will
        !          17864: add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of
        !          17865: other things, plus on-line documentation.  We hope to supply, eventually,
        !          17866: everything useful that normally comes with a Unix system, and more.
        !          17867: 
        !          17868: GNU will be able to run Unix programs, but will not be identical to Unix.
        !          17869: We will make all improvements that are convenient, based on our experience
        !          17870: with other operating systems.  In particular, we plan to have longer
        !          17871: filenames, file version numbers, a crashproof file system, filename
        !          17872: completion perhaps, terminal-independent display support, and perhaps
        !          17873: eventually a Lisp-based window system through which several Lisp programs
        !          17874: and ordinary Unix programs can share a screen.  Both C and Lisp will be
        !          17875: available as system programming languages.  We will try to support UUCP,
        !          17876: MIT Chaosnet, and Internet protocols for communication.
        !          17877: 
        !          17878: GNU is aimed initially at machines in the 68000/16000 class with virtual
        !          17879: memory, because they are the easiest machines to make it run on.  The extra
        !          17880: effort to make it run on smaller machines will be left to someone who wants
        !          17881: to use it on them.
        !          17882: 
        !          17883: To avoid horrible confusion, please pronounce the `G' in the word `GNU'
        !          17884: when it is the name of this project.
        !          17885: 
        !          17886: @unnumberedsec Why I Must Write GNU
        !          17887: 
        !          17888: I consider that the golden rule requires that if I like a program I must
        !          17889: share it with other people who like it.  Software sellers want to divide
        !          17890: the users and conquer them, making each user agree not to share with
        !          17891: others.  I refuse to break solidarity with other users in this way.  I
        !          17892: cannot in good conscience sign a nondisclosure agreement or a software
        !          17893: license agreement.  For years I worked within the Artificial Intelligence
        !          17894: Lab to resist such tendencies and other inhospitalities, but eventually
        !          17895: they had gone too far: I could not remain in an institution where such
        !          17896: things are done for me against my will.
        !          17897: 
        !          17898: So that I can continue to use computers without dishonor, I have decided to
        !          17899: put together a sufficient body of free software so that I will be able to
        !          17900: get along without any software that is not free.  I have resigned from the
        !          17901: AI lab to deny MIT any legal excuse to prevent me from giving GNU away.
        !          17902: 
        !          17903: @unnumberedsec Why GNU Will Be Compatible with Unix
        !          17904: 
        !          17905: Unix is not my ideal system, but it is not too bad.  The essential features
        !          17906: of Unix seem to be good ones, and I think I can fill in what Unix lacks
        !          17907: without spoiling them.  And a system compatible with Unix would be
        !          17908: convenient for many other people to adopt.
        !          17909: 
        !          17910: @unnumberedsec How GNU Will Be Available
        !          17911: 
        !          17912: GNU is not in the public domain.  Everyone will be permitted to modify and
        !          17913: redistribute GNU, but no distributor will be allowed to restrict its
        !          17914: further redistribution.  That is to say, proprietary modifications will not
        !          17915: be allowed.  I want to make sure that all versions of GNU remain free.
        !          17916: 
        !          17917: @unnumberedsec Why Many Other Programmers Want to Help
        !          17918: 
        !          17919: I have found many other programmers who are excited about GNU and want to
        !          17920: help.
        !          17921: 
        !          17922: Many programmers are unhappy about the commercialization of system
        !          17923: software.  It may enable them to make more money, but it requires them to
        !          17924: feel in conflict with other programmers in general rather than feel as
        !          17925: comrades.  The fundamental act of friendship among programmers is the
        !          17926: sharing of programs; marketing arrangements now typically used essentially
        !          17927: forbid programmers to treat others as friends.  The purchaser of software
        !          17928: must choose between friendship and obeying the law.  Naturally, many decide
        !          17929: that friendship is more important.  But those who believe in law often do
        !          17930: not feel at ease with either choice.  They become cynical and think that
        !          17931: programming is just a way of making money.
        !          17932: 
        !          17933: By working on and using GNU rather than proprietary programs, we can be
        !          17934: hospitable to everyone and obey the law.  In addition, GNU serves as an
        !          17935: example to inspire and a banner to rally others to join us in sharing.
        !          17936: This can give us a feeling of harmony which is impossible if we use
        !          17937: software that is not free.  For about half the programmers I talk to, this
        !          17938: is an important happiness that money cannot replace.
        !          17939: 
        !          17940: @unnumberedsec How You Can Contribute
        !          17941: 
        !          17942: I am asking computer manufacturers for donations of machines and money.
        !          17943: I'm asking individuals for donations of programs and work.
        !          17944: 
        !          17945: One consequence you can expect if you donate machines is that GNU will run
        !          17946: on them at an early date.  The machines should be complete, ready to use
        !          17947: systems, approved for use in a residential area, and not in need of
        !          17948: sophisticated cooling or power.
        !          17949: 
        !          17950: I have found very many programmers eager to contribute part-time work for
        !          17951: GNU.  For most projects, such part-time distributed work would be very hard
        !          17952: to coordinate; the independently-written parts would not work together.
        !          17953: But for the particular task of replacing Unix, this problem is absent.  A
        !          17954: complete Unix system contains hundreds of utility programs, each of which
        !          17955: is documented separately.  Most interface specifications are fixed by Unix
        !          17956: compatibility.  If each contributor can write a compatible replacement for
        !          17957: a single Unix utility, and make it work properly in place of the original
        !          17958: on a Unix system, then these utilities will work right when put together.
        !          17959: Even allowing for Murphy to create a few unexpected problems, assembling
        !          17960: these components will be a feasible task.  (The kernel will require closer
        !          17961: communication and will be worked on by a small, tight group.)
        !          17962: 
        !          17963: If I get donations of money, I may be able to hire a few people full or
        !          17964: part time.  The salary won't be high by programmers' standards, but I'm
        !          17965: looking for people for whom building community spirit is as important as
        !          17966: making money.  I view this as a way of enabling dedicated people to devote
        !          17967: their full energies to working on GNU by sparing them the need to make a
        !          17968: living in another way.
        !          17969: 
        !          17970: @unnumberedsec Why All Computer Users Will Benefit
        !          17971: 
        !          17972: Once GNU is written, everyone will be able to obtain good system software
        !          17973: free, just like air.
        !          17974: 
        !          17975: This means much more than just saving everyone the price of a Unix license.
        !          17976: It means that much wasteful duplication of system programming effort will
        !          17977: be avoided.  This effort can go instead into advancing the state of the
        !          17978: art.
        !          17979: 
        !          17980: Complete system sources will be available to everyone.  As a result, a user
        !          17981: who needs changes in the system will always be free to make them himself,
        !          17982: or hire any available programmer or company to make them for him.  Users
        !          17983: will no longer be at the mercy of one programmer or company which owns the
        !          17984: sources and is in sole position to make changes.
        !          17985: 
        !          17986: Schools will be able to provide a much more educational environment by
        !          17987: encouraging all students to study and improve the system code.  Harvard's
        !          17988: computer lab used to have the policy that no program could be installed on
        !          17989: the system if its sources were not on public display, and upheld it by
        !          17990: actually refusing to install certain programs.  I was very much inspired by
        !          17991: this.
        !          17992: 
        !          17993: Finally, the overhead of considering who owns the system software and what
        !          17994: one is or is not entitled to do with it will be lifted.
        !          17995: 
        !          17996: Arrangements to make people pay for using a program, including licensing of
        !          17997: copies, always incur a tremendous cost to society through the cumbersome
        !          17998: mechanisms necessary to figure out how much (that is, which programs) a
        !          17999: person must pay for.  And only a police state can force everyone to obey
        !          18000: them.  Consider a space station where air must be manufactured at great
        !          18001: cost: charging each breather per liter of air may be fair, but wearing the
        !          18002: metered gas mask all day and all night is intolerable even if everyone can
        !          18003: afford to pay the air bill.  And the TV cameras everywhere to see if you
        !          18004: ever take the mask off are outrageous.  It's better to support the air
        !          18005: plant with a head tax and chuck the masks.
        !          18006: 
        !          18007: Copying all or parts of a program is as natural to a programmer as
        !          18008: breathing, and as productive.  It ought to be as free.
        !          18009: 
        !          18010: @unnumberedsec Some Easily Rebutted Objections to GNU's Goals
        !          18011: 
        !          18012: @quotation
        !          18013: ``Nobody will use it if it is free, because that means they can't rely
        !          18014: on any support.''
        !          18015: 
        !          18016: ``You have to charge for the program to pay for providing the
        !          18017: support.''
        !          18018: @end quotation
        !          18019: 
        !          18020: If people would rather pay for GNU plus service than get GNU free without
        !          18021: service, a company to provide just service to people who have obtained GNU
        !          18022: free ought to be profitable.
        !          18023: 
        !          18024: We must distinguish between support in the form of real programming work
        !          18025: and mere handholding.  The former is something one cannot rely on from a
        !          18026: software vendor.  If your problem is not shared by enough people, the
        !          18027: vendor will tell you to get lost.
        !          18028: 
        !          18029: If your business needs to be able to rely on support, the only way is to
        !          18030: have all the necessary sources and tools.  Then you can hire any available
        !          18031: person to fix your problem; you are not at the mercy of any individual.
        !          18032: With Unix, the price of sources puts this out of consideration for most
        !          18033: businesses.  With GNU this will be easy.  It is still possible for there to
        !          18034: be no available competent person, but this problem cannot be blamed on
        !          18035: distribution arrangements.  GNU does not eliminate all the world's problems,
        !          18036: only some of them.
        !          18037: 
        !          18038: Meanwhile, the users who know nothing about computers need handholding:
        !          18039: doing things for them which they could easily do themselves but don't know
        !          18040: how.
        !          18041: 
        !          18042: Such services could be provided by companies that sell just hand-holding
        !          18043: and repair service.  If it is true that users would rather spend money and
        !          18044: get a product with service, they will also be willing to buy the service
        !          18045: having got the product free.  The service companies will compete in quality
        !          18046: and price; users will not be tied to any particular one.  Meanwhile, those
        !          18047: of us who don't need the service should be able to use the program without
        !          18048: paying for the service.
        !          18049: 
        !          18050: @quotation
        !          18051: ``You cannot reach many people without advertising,
        !          18052: and you must charge for the program to support that.''
        !          18053: 
        !          18054: ``It's no use advertising a program people can get free.''
        !          18055: @end quotation
        !          18056: 
        !          18057: There are various forms of free or very cheap publicity that can be used to
        !          18058: inform numbers of computer users about something like GNU.  But it may be
        !          18059: true that one can reach more microcomputer users with advertising.  If this
        !          18060: is really so, a business which advertises the service of copying and
        !          18061: mailing GNU for a fee ought to be successful enough to pay for its
        !          18062: advertising and more.  This way, only the users who benefit from the
        !          18063: advertising pay for it.
        !          18064: 
        !          18065: On the other hand, if many people get GNU from their friends, and such
        !          18066: companies don't succeed, this will show that advertising was not really
        !          18067: necessary to spread GNU.  Why is it that free market advocates don't want
        !          18068: to let the free market decide this?
        !          18069: 
        !          18070: @quotation
        !          18071: ``My company needs a proprietary operating system
        !          18072: to get a competitive edge.''
        !          18073: @end quotation
        !          18074: 
        !          18075: GNU will remove operating system software from the realm of competition.
        !          18076: You will not be able to get an edge in this area, but neither will your
        !          18077: competitors be able to get an edge over you.  You and they will compete in
        !          18078: other areas, while benefitting mutually in this one.  If your business is
        !          18079: selling an operating system, you will not like GNU, but that's tough on
        !          18080: you.  If your business is something else, GNU can save you from being
        !          18081: pushed into the expensive business of selling operating systems.
        !          18082: 
        !          18083: I would like to see GNU development supported by gifts from many
        !          18084: manufacturers and users, reducing the cost to each.
        !          18085: 
        !          18086: @quotation
        !          18087: ``Don't programmers deserve a reward for their creativity?''
        !          18088: @end quotation
        !          18089: 
        !          18090: If anything deserves a reward, it is social contribution.  Creativity can
        !          18091: be a social contribution, but only in so far as society is free to use the
        !          18092: results.  If programmers deserve to be rewarded for creating innovative
        !          18093: programs, by the same token they deserve to be punished if they restrict
        !          18094: the use of these programs.
        !          18095: 
        !          18096: @quotation
        !          18097: ``Shouldn't a programmer be able to ask for a reward for his creativity?''
        !          18098: @end quotation
        !          18099: 
        !          18100: There is nothing wrong with wanting pay for work, or seeking to maximize
        !          18101: one's income, as long as one does not use means that are destructive.  But
        !          18102: the means customary in the field of software today are based on
        !          18103: destruction.
        !          18104: 
        !          18105: Extracting money from users of a program by restricting their use of it is
        !          18106: destructive because the restrictions reduce the amount and the ways that
        !          18107: the program can be used.  This reduces the amount of wealth that humanity
        !          18108: derives from the program.  When there is a deliberate choice to restrict,
        !          18109: the harmful consequences are deliberate destruction.
        !          18110: 
        !          18111: The reason a good citizen does not use such destructive means to become
        !          18112: wealthier is that, if everyone did so, we would all become poorer from the
        !          18113: mutual destructiveness.  This is Kantian ethics; or, the Golden Rule.
        !          18114: Since I do not like the consequences that result if everyone hoards
        !          18115: information, I am required to consider it wrong for one to do so.
        !          18116: Specifically, the desire to be rewarded for one's creativity does not
        !          18117: justify depriving the world in general of all or part of that creativity.
        !          18118: 
        !          18119: @quotation
        !          18120: ``Won't programmers starve?''
        !          18121: @end quotation
        !          18122: 
        !          18123: I could answer that nobody is forced to be a programmer.  Most of us cannot
        !          18124: manage to get any money for standing on the street and making faces.  But
        !          18125: we are not, as a result, condemned to spend our lives standing on the
        !          18126: street making faces, and starving.  We do something else.
        !          18127: 
        !          18128: But that is the wrong answer because it accepts the questioner's implicit
        !          18129: assumption: that without ownership of software, programmers cannot possibly
        !          18130: be paid a cent.  Supposedly it is all or nothing.
        !          18131: 
        !          18132: The real reason programmers will not starve is that it will still be
        !          18133: possible for them to get paid for programming; just not paid as much as
        !          18134: now.
        !          18135: 
        !          18136: Restricting copying is not the only basis for business in software.  It is
        !          18137: the most common basis because it brings in the most money.  If it were
        !          18138: prohibited, or rejected by the customer, software business would move to
        !          18139: other bases of organization which are now used less often.  There are
        !          18140: always numerous ways to organize any kind of business.
        !          18141: 
        !          18142: Probably programming will not be as lucrative on the new basis as it is
        !          18143: now.  But that is not an argument against the change.  It is not considered
        !          18144: an injustice that sales clerks make the salaries that they now do.  If
        !          18145: programmers made the same, that would not be an injustice either.  (In
        !          18146: practice they would still make considerably more than that.)
        !          18147: 
        !          18148: @quotation
        !          18149: ``Don't people have a right to control how their creativity is used?''
        !          18150: @end quotation
        !          18151: 
        !          18152: ``Control over the use of one's ideas'' really constitutes control over
        !          18153: other people's lives; and it is usually used to make their lives more
        !          18154: difficult.
        !          18155: 
        !          18156: People who have studied the issue of intellectual property rights carefully
        !          18157: (such as lawyers) say that there is no intrinsic right to intellectual
        !          18158: property.  The kinds of supposed intellectual property rights that the
        !          18159: government recognizes were created by specific acts of legislation for
        !          18160: specific purposes.
        !          18161: 
        !          18162: For example, the patent system was established to encourage inventors to
        !          18163: disclose the details of their inventions.  Its purpose was to help society
        !          18164: rather than to help inventors.  At the time, the life span of 17 years for
        !          18165: a patent was short compared with the rate of advance of the state of the
        !          18166: art.  Since patents are an issue only among manufacturers, for whom the
        !          18167: cost and effort of a license agreement are small compared with setting up
        !          18168: production, the patents often do not do much harm.  They do not obstruct
        !          18169: most individuals who use patented products.
        !          18170: 
        !          18171: The idea of copyright did not exist in ancient times, when authors
        !          18172: frequently copied other authors at length in works of non-fiction.  This
        !          18173: practice was useful, and is the only way many authors' works have survived
        !          18174: even in part.  The copyright system was created expressly for the purpose
        !          18175: of encouraging authorship.  In the domain for which it was
        !          18176: invented---books, which could be copied economically only on a printing
        !          18177: press---it did little harm, and did not obstruct most of the individuals
        !          18178: who read the books.
        !          18179: 
        !          18180: All intellectual property rights are just licenses granted by society
        !          18181: because it was thought, rightly or wrongly, that society as a whole would
        !          18182: benefit by granting them.  But in any particular situation, we have to ask:
        !          18183: are we really better off granting such license?  What kind of act are we
        !          18184: licensing a person to do?
        !          18185: 
        !          18186: The case of programs today is very different from that of books a hundred
        !          18187: years ago.  The fact that the easiest way to copy a program is from one
        !          18188: neighbor to another, the fact that a program has both source code and
        !          18189: object code which are distinct, and the fact that a program is used rather
        !          18190: than read and enjoyed, combine to create a situation in which a person who
        !          18191: enforces a copyright is harming society as a whole both materially and
        !          18192: spiritually; in which a person should not do so regardless of whether the
        !          18193: law enables him to.
        !          18194: 
        !          18195: @quotation
        !          18196: ``Competition makes things get done better.''
        !          18197: @end quotation
        !          18198: 
        !          18199: The paradigm of competition is a race: by rewarding the winner, we
        !          18200: encourage everyone to run faster.  When capitalism really works this way,
        !          18201: it does a good job; but its defenders are wrong in assuming it always works
        !          18202: this way.  If the runners forget why the reward is offered and become
        !          18203: intent on winning, no matter how, they may find other strategies---such as,
        !          18204: attacking other runners.  If the runners get into a fist fight, they will
        !          18205: all finish late.
        !          18206: 
        !          18207: Proprietary and secret software is the moral equivalent of runners in a
        !          18208: fist fight.  Sad to say, the only referee we've got does not seem to
        !          18209: object to fights; he just regulates them (``For every ten yards you run,
        !          18210: you can fire one shot'').  He really ought to break them up, and penalize
        !          18211: runners for even trying to fight.
        !          18212: 
        !          18213: @quotation
        !          18214: ``Won't everyone stop programming without a monetary incentive?''
        !          18215: @end quotation
        !          18216: 
        !          18217: Actually, many people will program with absolutely no monetary incentive.
        !          18218: Programming has an irresistible fascination for some people, usually the
        !          18219: people who are best at it.  There is no shortage of professional musicians
        !          18220: who keep at it even though they have no hope of making a living that way.
        !          18221: 
        !          18222: But really this question, though commonly asked, is not appropriate to the
        !          18223: situation.  Pay for programmers will not disappear, only become less.  So
        !          18224: the right question is, will anyone program with a reduced monetary
        !          18225: incentive?  My experience shows that they will.
        !          18226: 
        !          18227: For more than ten years, many of the world's best programmers worked at the
        !          18228: Artificial Intelligence Lab for far less money than they could have had
        !          18229: anywhere else.  They got many kinds of non-monetary rewards: fame and
        !          18230: appreciation, for example.  And creativity is also fun, a reward in itself.
        !          18231: 
        !          18232: Then most of them left when offered a chance to do the same interesting
        !          18233: work for a lot of money.
        !          18234: 
        !          18235: What the facts show is that people will program for reasons other than
        !          18236: riches; but if given a chance to make a lot of money as well, they will
        !          18237: come to expect and demand it.  Low-paying organizations do poorly in
        !          18238: competition with high-paying ones, but they do not have to do badly if the
        !          18239: high-paying ones are banned.
        !          18240: 
        !          18241: @quotation
        !          18242: ``We need the programmers desperately.  If they demand that we
        !          18243: stop helping our neighbors, we have to obey.''
        !          18244: @end quotation
        !          18245: 
        !          18246: You're never so desperate that you have to obey this sort of demand.
        !          18247: Remember: millions for defense, but not a cent for tribute!
        !          18248: 
        !          18249: @quotation
        !          18250: ``Programmers need to make a living somehow.''
        !          18251: @end quotation
        !          18252: 
        !          18253: In the short run, this is true.  However, there are plenty of ways that
        !          18254: programmers could make a living without selling the right to use a program.
        !          18255: This way is customary now because it brings programmers and businessmen the
        !          18256: most money, not because it is the only way to make a living.  It is easy to
        !          18257: find other ways if you want to find them.  Here are a number of examples.
        !          18258: 
        !          18259: A manufacturer introducing a new computer will pay for the porting of
        !          18260: operating systems onto the new hardware.
        !          18261: 
        !          18262: The sale of teaching, hand-holding and maintenance services could also
        !          18263: employ programmers.
        !          18264: 
        !          18265: People with new ideas could distribute programs as freeware, asking for
        !          18266: donations from satisfied users, or selling hand-holding services.  I have
        !          18267: met people who are already working this way successfully.
        !          18268: 
        !          18269: Users with related needs can form users' groups, and pay dues.  A group
        !          18270: would contract with programming companies to write programs that the
        !          18271: group's members would like to use.
        !          18272: 
        !          18273: All sorts of development can be funded with a Software Tax:
        !          18274: 
        !          18275: @quotation
        !          18276: Suppose everyone who buys a computer has to pay x percent of
        !          18277: the price as a software tax.  The government gives this to
        !          18278: an agency like the NSF to spend on software development.
        !          18279: 
        !          18280: But if the computer buyer makes a donation to software development
        !          18281: himself, he can take a credit against the tax.  He can donate to
        !          18282: the project of his own choosing---often, chosen because he hopes to
        !          18283: use the results when it is done.  He can take a credit for any amount
        !          18284: of donation up to the total tax he had to pay.
        !          18285: 
        !          18286: The total tax rate could be decided by a vote of the payers of
        !          18287: the tax, weighted according to the amount they will be taxed on.
        !          18288: 
        !          18289: The consequences:
        !          18290: 
        !          18291: @itemize @bullet
        !          18292: @item
        !          18293: The computer-using community supports software development.
        !          18294: @item
        !          18295: This community decides what level of support is needed.
        !          18296: @item
        !          18297: Users who care which projects their share is spent on
        !          18298: can choose this for themselves.
        !          18299: @end itemize
        !          18300: @end quotation
        !          18301: 
        !          18302: In the long run, making programs free is a step toward the post-scarcity
        !          18303: world, where nobody will have to work very hard just to make a living.
        !          18304: People will be free to devote themselves to activities that are fun, such
        !          18305: as programming, after spending the necessary ten hours a week on required
        !          18306: tasks such as legislation, family counseling, robot repair and asteroid
        !          18307: prospecting.  There will be no need to be able to make a living from
        !          18308: programming.
        !          18309: 
        !          18310: We have already greatly reduced the amount of work that the whole society
        !          18311: must do for its actual productivity, but only a little of this has
        !          18312: translated itself into leisure for workers because much nonproductive
        !          18313: activity is required to accompany productive activity.  The main causes of
        !          18314: this are bureaucracy and isometric struggles against competition.  Free
        !          18315: software will greatly reduce these drains in the area of software
        !          18316: production.  We must do this, in order for technical gains in productivity
        !          18317: to translate into less work for us.
        !          18318: 
        !          18319: @node Glossary, Key Index, Intro, Top
        !          18320: @unnumbered Glossary
        !          18321: 
        !          18322: @table @asis
        !          18323: @need 150
        !          18324: @item Abbrev
        !          18325: An abbrev is a text string which expands into a different text string
        !          18326: when present in the buffer.  For example, you might define a short
        !          18327: word as an abbrev for a long phrase that you want to insert
        !          18328: frequently.  @xref{Abbrevs}.
        !          18329: 
        !          18330: @need 150
        !          18331: @item Aborting
        !          18332: Aborting means getting out of a recursive edit (q.v.@:).  The
        !          18333: commands @kbd{C-]} and @kbd{M-x top-level} are used for this.
        !          18334: @xref{Quitting}.
        !          18335: 
        !          18336: @need 150
        !          18337: @item Auto Fill mode
        !          18338: Auto Fill mode is a minor mode in which text that you insert is
        !          18339: automatically broken into lines of fixed width.  @xref{Filling}.
        !          18340: 
        !          18341: @need 150
        !          18342: @item Auto Saving
        !          18343: Auto saving is when Emacs automatically stores the contents of an
        !          18344: Emacs buffer in a specially-named file so that the information will
        !          18345: not be lost if the buffer is lost due to a system error or user error.
        !          18346: @xref{Auto Save}.
        !          18347: 
        !          18348: @need 150
        !          18349: @item Backup File
        !          18350: A backup file records the contents that a file had before the current
        !          18351: editing session.  Emacs makes backup files automatically to help you
        !          18352: track down or cancel changes you later regret making.  @xref{Backup}.
        !          18353: 
        !          18354: @need 150
        !          18355: @item Balance Parentheses
        !          18356: Emacs can balance parentheses manually or automatically.  Manual
        !          18357: balancing is done by the commands to move over balanced expressions
        !          18358: (@pxref{Lists}).  Automatic balancing is done by blinking the
        !          18359: parenthesis that matches one just inserted (@pxref{Matching,,Matching
        !          18360: Parens}).
        !          18361: 
        !          18362: @need 150
        !          18363: @item Bind
        !          18364: To bind a key is to change its binding (q.v.@:).  @xref{Rebinding}.
        !          18365: 
        !          18366: @need 150
        !          18367: @item Binding
        !          18368: A key gets its meaning in Emacs by having a binding which is a
        !          18369: command (q.v.@:), a Lisp function that is run when the key is typed.
        !          18370: @xref{Commands,Binding}.  Customization often involves rebinding a
        !          18371: character to a different command function.  The bindings of all keys
        !          18372: are recorded in the keymaps (q.v.@:).  @xref{Keymaps}.
        !          18373: 
        !          18374: @need 150
        !          18375: @item Blank Lines
        !          18376: Blank lines are lines that contain only whitespace.  Emacs has several
        !          18377: commands for operating on the blank lines in the buffer.
        !          18378: 
        !          18379: @need 150
        !          18380: @item Buffer
        !          18381: The buffer is the basic editing unit; one buffer corresponds to one
        !          18382: piece of text being edited.  You can have several buffers, but at any
        !          18383: time you are editing only one, the `selected' buffer, though several
        !          18384: can be visible when you are using multiple windows.  @xref{Buffers}.
        !          18385: 
        !          18386: @need 150
        !          18387: @item Buffer Selection History
        !          18388: Emacs keeps a buffer selection history which records how recently each
        !          18389: Emacs buffer has been selected.  This is used for choosing a buffer to
        !          18390: select.  @xref{Buffers}.
        !          18391: 
        !          18392: @need 150
        !          18393: @item C-
        !          18394: @samp{C} in the name of a character is an abbreviation for Control.
        !          18395: @xref{Characters,C-}.
        !          18396: 
        !          18397: @need 150
        !          18398: @item C-M-
        !          18399: @samp{C-M-} in the name of a character is an abbreviation for
        !          18400: Control-Meta.  @xref{Characters,C-M-}.
        !          18401: 
        !          18402: @need 150
        !          18403: @item Case Conversion
        !          18404: Case conversion means changing text from upper case to lower case or
        !          18405: vice versa.  @xref{Case}, for the commands for case conversion.
        !          18406: 
        !          18407: @need 150
        !          18408: @item Characters
        !          18409: Characters form the contents of an Emacs buffer; also, Emacs commands
        !          18410: are invoked by keys (q.v.@:), which are sequences of one or more
        !          18411: characters.  @xref{Characters}.
        !          18412: 
        !          18413: @need 150
        !          18414: @item Command
        !          18415: A command is a Lisp function specially defined to be able to serve as
        !          18416: a key binding in Emacs.  When you type a key (q.v.@:), its binding
        !          18417: (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find the
        !          18418: command to run.  @xref{Commands}.
        !          18419: 
        !          18420: @need 150
        !          18421: @item Command Name
        !          18422: A command name is the name of a Lisp symbol which is a command
        !          18423: (@pxref{Commands}).  You can invoke any command by its name using
        !          18424: @kbd{M-x} (@pxref{M-x}).
        !          18425: 
        !          18426: @need 150
        !          18427: @item Comments
        !          18428: A comment is text in a program which is intended only for humans
        !          18429: reading the program, and is marked specially so that it will be
        !          18430: ignored when the program is loaded or compiled.  Emacs offers special
        !          18431: commands for creating, aligning and killing comments.
        !          18432: @xref{Comments}.
        !          18433: 
        !          18434: @need 150
        !          18435: @item Compilation
        !          18436: Compilation is the process of creating an executable program from
        !          18437: source code.  Emacs has commands for compiling files of Emacs Lisp
        !          18438: code (@pxref{Lisp Libraries}) and programs in C and other languages
        !          18439: (@pxref{Compilation}).
        !          18440: 
        !          18441: @need 150
        !          18442: @item Complete Key
        !          18443: A complete key is a character or sequence of characters which, when typed
        !          18444: by the user, fully specifies one action to be performed by Emacs.  For
        !          18445: example, @kbd{X} and @kbd{Control-f} and @kbd{Control-x m} are keys.  Keys
        !          18446: derive their meanings from being bound (q.v.@:) to commands (q.v.@:).
        !          18447: Thus, @kbd{X} is conventionally bound to a command to insert @samp{X} in
        !          18448: the buffer; @kbd{C-x m} is conventionally bound to a command to begin
        !          18449: composing a mail message. @xref{Keys}.
        !          18450: 
        !          18451: @need 150
        !          18452: @item Completion
        !          18453: Completion is what Emacs does when it automatically fills out an
        !          18454: abbreviation for a name into the entire name.  Completion is done for
        !          18455: minibuffer (q.v.@:) arguments when the set of possible valid inputs
        !          18456: is known; for example, on command names, buffer names, and
        !          18457: file names.  Completion occurs when @key{TAB}, @key{SPC} or @key{RET}
        !          18458: is typed.  @xref{Completion}.@refill
        !          18459: 
        !          18460: @need 150
        !          18461: @item Continuation Line
        !          18462: When a line of text is longer than the width of the screen, it
        !          18463: takes up more than one screen line when displayed.  We say that the
        !          18464: text line is continued, and all screen lines used for it after the
        !          18465: first are called continuation lines.  @xref{Basic,Continuation,Basic
        !          18466: Editing}.
        !          18467: 
        !          18468: @need 150
        !          18469: @item Control-Character
        !          18470: @sc{ascii} characters with octal codes 0 through 037, and also code 0177,
        !          18471: do not have graphic images assigned to them.  These are the control
        !          18472: characters.  Any control character can be typed by holding down the
        !          18473: @key{CTRL} key and typing some other character; some have special keys
        !          18474: on the keyboard.  @key{RET}, @key{TAB}, @key{ESC}, @key{LFD} and
        !          18475: @key{DEL} are all control characters.  @xref{Characters}.@refill
        !          18476: 
        !          18477: @need 150
        !          18478: @item Copyleft
        !          18479: A copyleft is a notice giving the public legal permission to redistribute
        !          18480: a program or other work of art.  Copylefts are used by leftists to enrich
        !          18481: the public just as copyrights are used by rightists to gain power over
        !          18482: the public.
        !          18483: 
        !          18484: @need 150
        !          18485: @item Current Buffer
        !          18486: The current buffer in Emacs is the Emacs buffer on which most editing
        !          18487: commands operate.  You can select any Emacs buffer as the current one.
        !          18488: @xref{Buffers}.
        !          18489: 
        !          18490: @need 150
        !          18491: @item Current Line
        !          18492: The line point is on (@pxref{Point}).
        !          18493: 
        !          18494: @need 150
        !          18495: @item Current Paragraph
        !          18496: The paragraph that point is in.  If point is between paragraphs, the
        !          18497: current paragraph is the one that follows point.  @xref{Paragraphs}.
        !          18498: 
        !          18499: @need 150
        !          18500: @item Current Defun
        !          18501: The defun (q.v.@:) that point is in.  If point is between defuns, the
        !          18502: current defun is the one that follows point.  @xref{Defuns}.
        !          18503: 
        !          18504: @need 150
        !          18505: @item Cursor
        !          18506: The cursor is the rectangle on the screen which indicates the position
        !          18507: called point (q.v.@:) at which insertion and deletion takes place.
        !          18508: The cursor is on or under the character that follows point.  Often
        !          18509: people speak of `the cursor' when, strictly speaking, they mean
        !          18510: `point'.  @xref{Basic,Cursor,Basic Editing}.
        !          18511: 
        !          18512: @need 150
        !          18513: @item Customization
        !          18514: Customization is making minor changes in the way Emacs works.  It is
        !          18515: often done by setting variables (@pxref{Variables}) or by rebinding
        !          18516: keys (@pxref{Keymaps}).
        !          18517: 
        !          18518: @need 150
        !          18519: @item Default Argument
        !          18520: The default for an argument is the value that will be assumed if you
        !          18521: do not specify one.  When the minibuffer is used to read an argument,
        !          18522: the default argument is used if you just type @key{RET}.
        !          18523: @xref{Minibuffer}.
        !          18524: 
        !          18525: @need 150
        !          18526: @item Default Directory
        !          18527: When you specify a file name that does not start with @samp{/} or @samp{~},
        !          18528: it is interpreted relative to the current buffer's default directory.
        !          18529: @xref{Minibuffer File,Default Directory}.
        !          18530: 
        !          18531: @need 150
        !          18532: @item Defun
        !          18533: A defun is a list at the top level of parenthesis or bracket structure
        !          18534: in a program.  It is so named because most such lists in Lisp programs
        !          18535: are calls to the Lisp function @code{defun}.  @xref{Defuns}.
        !          18536: 
        !          18537: @need 150
        !          18538: @item @key{DEL}
        !          18539: @key{DEL} is a character that runs the command to delete one character of
        !          18540: text.  @xref{Basic,DEL,Basic Editing}.
        !          18541: 
        !          18542: @need 150
        !          18543: @item Deletion
        !          18544: Deletion means erasing text without saving it.  Emacs deletes text
        !          18545: only when it is expected not to be worth saving (all whitespace, or
        !          18546: only one character).  The alternative is killing (q.v.@:).
        !          18547: @xref{Killing,Deletion}.
        !          18548: 
        !          18549: @need 150
        !          18550: @item Deletion of Files
        !          18551: Deleting a file means erasing it from the file system.
        !          18552: @xref{Misc File Ops}.
        !          18553: 
        !          18554: @need 150
        !          18555: @item Deletion of Messages
        !          18556: Deleting a message means flagging it to be eliminated from your mail
        !          18557: file.  This can be undone by undeletion until the mail file is expunged.
        !          18558: @xref{Rmail Deletion}.
        !          18559: 
        !          18560: @need 150
        !          18561: @item Deletion of Windows
        !          18562: Deleting a window means eliminating it from the screen.  Other windows
        !          18563: expand to use up the space.  The deleted window can never come back,
        !          18564: but no actual text is thereby lost.  @xref{Windows}.
        !          18565: 
        !          18566: @need 150
        !          18567: @item Directory
        !          18568: Files in the Unix file system are grouped into file directories.
        !          18569: @xref{ListDir,,Directories}.
        !          18570: 
        !          18571: @need 150
        !          18572: @item Dired
        !          18573: Dired is the Emacs facility that displays the contents of a file
        !          18574: directory and allows you to ``edit the directory'', performing
        !          18575: operations on the files in the directory.  @xref{Dired}.
        !          18576: 
        !          18577: @need 150
        !          18578: @item Disabled Command
        !          18579: A disabled command is one that you may not run without special
        !          18580: confirmation.  The usual reason for disabling a command is that it is
        !          18581: confusing for beginning users.  @xref{Disabling}.
        !          18582: 
        !          18583: @need 150
        !          18584: @item Dribble File
        !          18585: A file into which Emacs writes all the characters that the user types
        !          18586: on the keyboard.  Dribble files are used to make a record for
        !          18587: debugging Emacs bugs.  Emacs does not make a dribble file unless you
        !          18588: tell it to.  @xref{Bugs}.
        !          18589: 
        !          18590: @need 150
        !          18591: @item Echo Area
        !          18592: The echo area is the bottom line of the screen, used for echoing the
        !          18593: arguments to commands, for asking questions, and printing brief
        !          18594: messages (including error messages).  @xref{Echo Area}.
        !          18595: 
        !          18596: @need 150
        !          18597: @item Echoing
        !          18598: Echoing is acknowledging the receipt of commands by displaying them
        !          18599: (in the echo area).  Emacs never echoes single-character keys; longer
        !          18600: keys echo only if you pause while typing them.
        !          18601: 
        !          18602: @need 150
        !          18603: @item Error
        !          18604: An error occurs when an Emacs command cannot execute in the current
        !          18605: circumstances.  When an error occurs, execution of the command stops
        !          18606: (unless the command has been programmed to do otherwise) and Emacs
        !          18607: reports the error by printing an error message (q.v.).  Type-ahead
        !          18608: is discarded.  Then Emacs is ready to read another editing command.
        !          18609: 
        !          18610: @need 150
        !          18611: @item Error Messages
        !          18612: Error messages are single lines of output printed by Emacs when the
        !          18613: user asks for something impossible to do (such as, killing text
        !          18614: forward when point is at the end of the buffer).  They appear in the
        !          18615: echo area, accompanied by a beep.
        !          18616: 
        !          18617: @need 150
        !          18618: @item @key{ESC}
        !          18619: @key{ESC} is a character, used to end incremental searches and as a
        !          18620: prefix for typing Meta characters on keyboards lacking a @key{META}
        !          18621: key.  Unlike the @key{META} key (which, like the @key{SHIFT} key, is held
        !          18622: down while another character is typed), the @key{ESC} key is pressed
        !          18623: once and applies to the next character typed.
        !          18624: 
        !          18625: @need 150
        !          18626: @item Fill Prefix
        !          18627: The fill prefix is a string that should be expected at the beginning
        !          18628: of each line when filling is done.  It is not regarded as part of the
        !          18629: text to be filled.  @xref{Filling}.
        !          18630: 
        !          18631: @need 150
        !          18632: @item Filling
        !          18633: Filling text means moving text from line to line so that all the lines
        !          18634: are approximately the same length.  @xref{Filling}.
        !          18635: 
        !          18636: @need 150
        !          18637: @item Global
        !          18638: Global means `independent of the current environment; in effect
        !          18639: throughout Emacs'.  It is the opposite of local (q.v.@:).  Particular
        !          18640: examples of the use of `global' appear below.
        !          18641: 
        !          18642: @need 150
        !          18643: @item Global Abbrev
        !          18644: A global definition of an abbrev (q.v.@:) is effective in all major
        !          18645: modes that do not have local (q.v.@:) definitions for the same abbrev.
        !          18646: @xref{Abbrevs}.
        !          18647: 
        !          18648: @need 150
        !          18649: @item Global Keymap
        !          18650: The global keymap (q.v.@:) contains key bindings that are in effect
        !          18651: except when overridden by local key bindings in a major mode's local
        !          18652: keymap (q.v.@:).  @xref{Keymaps}.
        !          18653: 
        !          18654: @need 150
        !          18655: @item Global Substitution
        !          18656: Global substitution means replacing each occurrence of one string by
        !          18657: another string through a large amount of text.  @xref{Replace}.
        !          18658: 
        !          18659: @need 150
        !          18660: @item Global Variable
        !          18661: The global value of a variable (q.v.@:) takes effect in all buffers
        !          18662: that do not have their own local (q.v.@:) values for the variable.
        !          18663: @xref{Variables}.
        !          18664: 
        !          18665: @need 150
        !          18666: @item Graphic Character
        !          18667: Graphic characters are those assigned pictorial images rather than
        !          18668: just names.  All the non-Meta (q.v.@:) characters except for the
        !          18669: Control (q.v.@:) characters are graphic characters.  These include
        !          18670: letters, digits, punctuation, and spaces; they do not include
        !          18671: @key{RET} or @key{ESC}.  In Emacs, typing a graphic character inserts
        !          18672: that character (in ordinary editing modes).  @xref{Basic,,Basic Editing}.
        !          18673: 
        !          18674: @need 150
        !          18675: @item Grinding
        !          18676: Grinding means adjusting the indentation in a program to fit the
        !          18677: nesting structure.  @xref{Indentation,Grinding}.
        !          18678: 
        !          18679: @need 150
        !          18680: @item Hardcopy
        !          18681: Hardcopy means printed output.  Emacs has commands for making printed
        !          18682: listings of text in Emacs buffers.  @xref{Hardcopy}.
        !          18683: 
        !          18684: @need 150
        !          18685: @item @key{HELP}
        !          18686: You can type @key{HELP} at any time to ask what options you have, or
        !          18687: to ask what any command does.  @key{HELP} is really @kbd{Control-h}.
        !          18688: @xref{Help}.
        !          18689: 
        !          18690: @need 150
        !          18691: @item Inbox
        !          18692: An inbox is a file in which mail is delivered by the operating system.
        !          18693: Rmail transfers mail from inboxes to mail files (q.v.) in which the
        !          18694: mail is then stored permanently or until explicitly deleted.
        !          18695: @xref{Rmail Inbox}.
        !          18696: 
        !          18697: @need 150
        !          18698: @item Indentation
        !          18699: Indentation means blank space at the beginning of a line.  Most
        !          18700: programming languages have conventions for using indentation to
        !          18701: illuminate the structure of the program, and Emacs has special
        !          18702: features to help you set up the correct indentation.
        !          18703: @xref{Indentation}.
        !          18704: 
        !          18705: @need 150
        !          18706: @item Insertion
        !          18707: Insertion means copying text into the buffer, either from the keyboard
        !          18708: or from some other place in Emacs.
        !          18709: 
        !          18710: @need 150
        !          18711: @item Justification
        !          18712: Justification means adding extra spaces to lines of text to make them
        !          18713: come exactly to a specified width.  @xref{Filling,Justification}.
        !          18714: 
        !          18715: @need 150
        !          18716: @item Keyboard Macros
        !          18717: Keyboard macros are a way of defining new Emacs commands from
        !          18718: sequences of existing ones, with no need to write a Lisp program.
        !          18719: @xref{Keyboard Macros}.
        !          18720: 
        !          18721: @need 150
        !          18722: @item Key
        !          18723: A key is a sequence of characters that, when input to Emacs, specify
        !          18724: or begin to specify a single action for Emacs to perform.  That is,
        !          18725: the sequence is not more than a single unit.  If the key is enough to
        !          18726: specify one action, it is a complete key (q.v.); if it is less than
        !          18727: enough, it is a prefix key (q.v.).  @xref{Keys}.
        !          18728: 
        !          18729: @need 150
        !          18730: @item Keymap
        !          18731: The keymap is the data structure that records the bindings (q.v.@:) of
        !          18732: keys to the commands that they run.  For example, the keymap binds the
        !          18733: character @kbd{C-n} to the command function @code{next-line}.
        !          18734: @xref{Keymaps}.
        !          18735: 
        !          18736: @need 150
        !          18737: @item Kill Ring
        !          18738: The kill ring is where all text you have killed recently is saved.
        !          18739: You can reinsert any of the killed text still in the ring; this is
        !          18740: called yanking (q.v.@:).  @xref{Yanking}.
        !          18741: 
        !          18742: @need 150
        !          18743: @item Killing
        !          18744: Killing means erasing text and saving it on the kill ring so it can be
        !          18745: yanked (q.v.@:) later.  Some other systems call this ``cutting''.
        !          18746: Most Emacs commands to erase text do killing, as opposed to deletion
        !          18747: (q.v.@:).  @xref{Killing}.
        !          18748: 
        !          18749: @need 150
        !          18750: @item Killing Jobs
        !          18751: Killing a job (such as, an invocation of Emacs) means making it cease
        !          18752: to exist.  Any data within it, if not saved in a file, is lost.
        !          18753: @xref{Exiting}.
        !          18754: 
        !          18755: @need 150
        !          18756: @item List
        !          18757: A list is, approximately, a text string beginning with an open
        !          18758: parenthesis and ending with the matching close parenthesis.  In C mode
        !          18759: and other non-Lisp modes, groupings surrounded by other kinds of matched
        !          18760: delimiters appropriate to the language, such as braces, are also
        !          18761: considered lists.  Emacs has special commands for many operations on
        !          18762: lists.  @xref{Lists}.
        !          18763: 
        !          18764: @need 150
        !          18765: @item Local
        !          18766: Local means `in effect only in a particular context'; the relevant
        !          18767: kind of context is a particular function execution, a particular
        !          18768: buffer, or a particular major mode.  It is the opposite of `global'
        !          18769: (q.v.@:).  Specific uses of `local' in Emacs terminology appear below.
        !          18770: 
        !          18771: @need 150
        !          18772: @item Local Abbrev
        !          18773: A local abbrev definition is effective only if a particular major mode
        !          18774: is selected.  In that major mode, it overrides any global definition
        !          18775: for the same abbrev.  @xref{Abbrevs}.
        !          18776: 
        !          18777: @need 150
        !          18778: @item Local Keymap
        !          18779: A local keymap is used in a particular major mode; the key bindings
        !          18780: (q.v.@:) in the current local keymap override global bindings of the
        !          18781: same keys.  @xref{Keymaps}.
        !          18782: 
        !          18783: @need 150
        !          18784: @item Local Variable
        !          18785: A local value of a variable (q.v.@:) applies to only one buffer.
        !          18786: @xref{Locals}.
        !          18787: 
        !          18788: @need 150
        !          18789: @item M-
        !          18790: @kbd{M-} in the name of a character is an abbreviation for @key{META},
        !          18791: one of the modifier keys that can accompany any character.
        !          18792: @xref{Characters}.
        !          18793: 
        !          18794: @need 150
        !          18795: @item M-C-
        !          18796: @samp{M-C-} in the name of a character is an abbreviation for
        !          18797: Control-Meta; it means the same thing as @samp{C-M-}.  If your
        !          18798: terminal lacks a real @key{META} key, you type a Control-Meta character by
        !          18799: typing @key{ESC} and then typing the corresponding Control character.
        !          18800: @xref{Characters,C-M-}.
        !          18801: 
        !          18802: @need 150
        !          18803: @item M-x
        !          18804: @kbd{M-x} is the key which is used to call an Emacs command by name.
        !          18805: This is how commands that are not bound to keys are called.
        !          18806: @xref{M-x}.
        !          18807: 
        !          18808: @need 150
        !          18809: @item Mail
        !          18810: Mail means messages sent from one user to another through the computer
        !          18811: system, to be read at the recipient's convenience.  Emacs has commands for
        !          18812: composing and sending mail, and for reading and editing the mail you have
        !          18813: received.  @xref{Sending Mail}.  @xref{Rmail}, for how to read mail.
        !          18814: 
        !          18815: @need 150
        !          18816: @item Mail File
        !          18817: A mail file is a file which is edited using Rmail and in which Rmail
        !          18818: stores mail.  @xref{Rmail}.
        !          18819: 
        !          18820: @need 150
        !          18821: @item Major Mode
        !          18822: The major modes are a mutually exclusive set of options each of which
        !          18823: configures Emacs for editing a certain sort of text.  Ideally, each
        !          18824: programming language has its own major mode.  @xref{Major Modes}.
        !          18825: 
        !          18826: @need 150
        !          18827: @item Mark
        !          18828: The mark points to a position in the text.  It specifies one end of
        !          18829: the region (q.v.@:), point being the other end.  Many commands operate
        !          18830: on all the text from point to the mark.  @xref{Mark}.
        !          18831: 
        !          18832: @need 150
        !          18833: @item Mark Ring
        !          18834: The mark ring is used to hold several recent previous locations of the
        !          18835: mark, just in case you want to move back to them.  @xref{Mark Ring}.
        !          18836: 
        !          18837: @need 150
        !          18838: @item Message
        !          18839: See `mail'.
        !          18840: 
        !          18841: @need 150
        !          18842: @item Meta
        !          18843: Meta is the name of a modifier bit which a command character may have.
        !          18844: It is present in a character if the character is typed with the
        !          18845: @key{META} key held down.  Such characters are given names that start
        !          18846: with @kbd{Meta-}.  For example, @kbd{Meta-<} is typed by holding down
        !          18847: @key{META} and at the same time typing @kbd{<} (which itself is done,
        !          18848: on most terminals, by holding down @key{SHIFT} and typing @kbd{,}).
        !          18849: @xref{Characters,Meta}.
        !          18850: 
        !          18851: @need 150
        !          18852: @item Meta Character
        !          18853: A Meta character is one whose character code includes the Meta bit.
        !          18854: 
        !          18855: @need 150
        !          18856: @item Minibuffer
        !          18857: The minibuffer is the window that appears when necessary inside the
        !          18858: echo area (q.v.@:), used for reading arguments to commands.
        !          18859: @xref{Minibuffer}.
        !          18860: 
        !          18861: @need 150
        !          18862: @item Minor Mode
        !          18863: A minor mode is an optional feature of Emacs which can be switched on
        !          18864: or off independently of all other features.  Each minor mode has a
        !          18865: command to turn it on or off.  @xref{Minor Modes}.
        !          18866: 
        !          18867: @need 150
        !          18868: @item Mode Line
        !          18869: The mode line is the line at the bottom of each text window (q.v.@:),
        !          18870: which gives status information on the buffer displayed in that window.
        !          18871: @xref{Mode Line}.
        !          18872: 
        !          18873: @need 150
        !          18874: @item Modified Buffer
        !          18875: A buffer (q.v.@:) is modified if its text has been changed since the
        !          18876: last time the buffer was saved (or since when it was created, if it
        !          18877: has never been saved).  @xref{Saving}.
        !          18878: 
        !          18879: @need 150
        !          18880: @item Moving Text
        !          18881: Moving text means erasing it from one place and inserting it in
        !          18882: another.  This is done by killing (q.v.@:) and then yanking (q.v.@:).
        !          18883: @xref{Killing}.
        !          18884: 
        !          18885: @need 150
        !          18886: @item Named Mark
        !          18887: A named mark is a register (q.v.@:) in its role of recording a
        !          18888: location in text so that you can move point to that location.
        !          18889: @xref{Registers}.
        !          18890: 
        !          18891: @need 150
        !          18892: @item Narrowing
        !          18893: Narrowing means creating a restriction (q.v.@:) that limits editing in
        !          18894: the current buffer to only a part of the text in the buffer.  Text
        !          18895: outside that part is inaccessible to the user until the boundaries are
        !          18896: widened again, but it is still there, and saving the file saves it
        !          18897: all.  @xref{Narrowing}.
        !          18898: 
        !          18899: @need 150
        !          18900: @item Newline
        !          18901: @key{LFD} characters in the buffer terminate lines of text and are
        !          18902: called newlines.  @xref{Characters,Newline}.
        !          18903: 
        !          18904: @need 150
        !          18905: @item Numeric Argument
        !          18906: A numeric argument is a number, specified before a command, to change
        !          18907: the effect of the command.  Often the numeric argument serves as a
        !          18908: repeat count.  @xref{Arguments}.
        !          18909: 
        !          18910: @need 150
        !          18911: @item Option
        !          18912: An option is a variable (q.v.@:) that exists so that you can customize
        !          18913: Emacs by giving it a new value.  @xref{Variables}.
        !          18914: 
        !          18915: @need 150
        !          18916: @item Overwrite Mode
        !          18917: Overwrite mode is a minor mode.  When it is enabled, ordinary text
        !          18918: characters replace the existing text after point rather than pushing
        !          18919: it to the right.  @xref{Minor Modes}.
        !          18920: 
        !          18921: @need 150
        !          18922: @item Page
        !          18923: A page is a unit of text, delimited by formfeed characters (@sc{ascii}
        !          18924: Control-L, code 014) coming at the beginning of a line.  Some Emacs
        !          18925: commands are provided for moving over and operating on pages.
        !          18926: @xref{Pages}.
        !          18927: 
        !          18928: @need 150
        !          18929: @item Paragraphs
        !          18930: Paragraphs are the medium-size unit of English text.  There are
        !          18931: special Emacs commands for moving over and operating on paragraphs.
        !          18932: @xref{Paragraphs}.
        !          18933: 
        !          18934: @need 150
        !          18935: @item Parsing
        !          18936: We say that Emacs parses words or expressions in the text being
        !          18937: edited.  Really, all it knows how to do is find the other end of a
        !          18938: word or expression.  @xref{Syntax}.
        !          18939: 
        !          18940: @need 150
        !          18941: @item Point
        !          18942: Point is the place in the buffer at which insertion and deletion
        !          18943: occur.  Point is considered to be between two characters, not at one
        !          18944: character.  The terminal's cursor (q.v.@:) indicates the location of
        !          18945: point.  @xref{Basic,Point}.
        !          18946: 
        !          18947: @need 150
        !          18948: @item Prefix Key
        !          18949: A prefix key is a key (q.v.@:) whose sole function is to introduce a
        !          18950: set of multi-character keys.  @kbd{Control-x} is an example of prefix
        !          18951: key; thus, any two-character sequence starting with @kbd{C-x} is also
        !          18952: a legitimate key.  @xref{Keys}.
        !          18953: 
        !          18954: @need 150
        !          18955: @item Primary Mail File
        !          18956: Your primary mail file is the file named @samp{RMAIL} in your home
        !          18957: directory, where all mail that you receive is stored by Rmail unless you
        !          18958: make arrangements to do otherwise.  @xref{Rmail}.
        !          18959: 
        !          18960: @need 150
        !          18961: @item Prompt
        !          18962: A prompt is text printed to ask the user for input.  Printing a prompt
        !          18963: is called prompting.  Emacs prompts always appear in the echo area
        !          18964: (q.v.@:).  One kind of prompting happens when the minibuffer is used
        !          18965: to read an argument (@pxref{Minibuffer}); the echoing which happens
        !          18966: when you pause in the middle of typing a multicharacter key is also a
        !          18967: kind of prompting (@pxref{Echo Area}).
        !          18968: 
        !          18969: @need 150
        !          18970: @item Quitting
        !          18971: Quitting means cancelling a partially typed command or a running
        !          18972: command, using @kbd{C-g}.  @xref{Quitting}.
        !          18973: 
        !          18974: @need 150
        !          18975: @item Quoting
        !          18976: Quoting means depriving a character of its usual special significance.
        !          18977: In Emacs this is usually done with @kbd{Control-q}.  What constitutes special
        !          18978: significance depends on the context and on convention.  For example,
        !          18979: an ``ordinary'' character as an Emacs command inserts itself; so in
        !          18980: this context, a special character is any character that does not
        !          18981: normally insert itself (such as @key{DEL}, for example), and quoting
        !          18982: it makes it insert itself as if it were not special.  Not all contexts
        !          18983: allow quoting.  @xref{Basic,Quoting,Basic Editing}.
        !          18984: 
        !          18985: @need 150
        !          18986: @item Read-only Buffer
        !          18987: A read-only buffer is one whose text you are not allowed to change.
        !          18988: Normally Emacs makes buffers read-only when they contain text which
        !          18989: has a special significance to Emacs; for example, Dired buffers.
        !          18990: Visiting a file that is write protected also makes a read-only buffer.
        !          18991: @xref{Buffers}.
        !          18992: 
        !          18993: @need 150
        !          18994: @item Recursive Editing Level
        !          18995: A recursive editing level is a state in which part of the execution of
        !          18996: a command involves asking the user to edit some text.  This text may
        !          18997: or may not be the same as the text to which the command was applied.
        !          18998: The mode line indicates recursive editing levels with square brackets
        !          18999: (@samp{[} and @samp{]}).  @xref{Recursive Edit}.
        !          19000: 
        !          19001: @need 150
        !          19002: @item Redisplay
        !          19003: Redisplay is the process of correcting the image on the screen to
        !          19004: correspond to changes that have been made in the text being edited.
        !          19005: @xref{Screen,Redisplay}.
        !          19006: 
        !          19007: @need 150
        !          19008: @item Regexp
        !          19009: See `regular expression'.
        !          19010: 
        !          19011: @need 150
        !          19012: @item Region
        !          19013: The region is the text between point (q.v.@:) and the mark (q.v.@:).
        !          19014: Many commands operate on the text of the region.  @xref{Mark,Region}.
        !          19015: 
        !          19016: @need 150
        !          19017: @item Registers
        !          19018: Registers are named slots in which text or buffer positions or
        !          19019: rectangles can be saved for later use.  @xref{Registers}.
        !          19020: 
        !          19021: @need 150
        !          19022: @item Regular Expression
        !          19023: A regular expression is a pattern that can match various text strings;
        !          19024: for example, @samp{l[0-9]+} matches @samp{l} followed by one or more
        !          19025: digits.  @xref{Regexps}.
        !          19026: 
        !          19027: @need 150
        !          19028: @item Replacement
        !          19029: See `global substitution'.
        !          19030: 
        !          19031: @need 150
        !          19032: @item Restriction
        !          19033: A buffer's restriction is the amount of text, at the beginning or the
        !          19034: end of the buffer, that is temporarily invisible and inaccessible.
        !          19035: Giving a buffer a nonzero amount of restriction is called narrowing
        !          19036: (q.v.).  @xref{Narrowing}.
        !          19037: 
        !          19038: @need 150
        !          19039: @item @key{RET}
        !          19040: @key{RET} is a character that in Emacs runs the command to insert a
        !          19041: newline into the text.  It is also used to terminate most arguments
        !          19042: read in the minibuffer (q.v.@:).  @xref{Characters,Return}.
        !          19043: 
        !          19044: @need 150
        !          19045: @item Saving
        !          19046: Saving a buffer means copying its text into the file that was visited
        !          19047: (q.v.@:) in that buffer.  This is the way text in files actually gets
        !          19048: changed by your Emacs editing.  @xref{Saving}.
        !          19049: 
        !          19050: @need 150
        !          19051: @item Scrolling
        !          19052: Scrolling means shifting the text in the Emacs window so as to see a
        !          19053: different part of the buffer.  @xref{Display,Scrolling}.
        !          19054: 
        !          19055: @need 150
        !          19056: @item Searching
        !          19057: Searching means moving point to the next occurrence of a specified
        !          19058: string.  @xref{Search}.
        !          19059: 
        !          19060: @need 150
        !          19061: @item Selecting
        !          19062: Selecting a buffer means making it the current (q.v.@:) buffer.
        !          19063: @xref{Buffers,Selecting}.
        !          19064: 
        !          19065: @need 150
        !          19066: @item Self-documentation
        !          19067: Self-documentation is the feature of Emacs which can tell you what any
        !          19068: command does, or give you a list of all commands related to a topic
        !          19069: you specify.  You ask for self-documentation with the help character,
        !          19070: @kbd{C-h}.  @xref{Help}.
        !          19071: 
        !          19072: @need 150
        !          19073: @item Sentences
        !          19074: Emacs has commands for moving by or killing by sentences.
        !          19075: @xref{Sentences}.
        !          19076: 
        !          19077: @need 150
        !          19078: @item Sexp
        !          19079: A sexp (short for `s-expression') is the basic syntactic unit of Lisp
        !          19080: in its textual form: either a list, or Lisp atom.  Many Emacs commands
        !          19081: operate on sexps.  The term `sexp' is generalized to languages other
        !          19082: than Lisp, to mean a syntactically recognizable expression.
        !          19083: @xref{Lists,Sexps}.
        !          19084: 
        !          19085: @need 150
        !          19086: @item Simultaneous Editing
        !          19087: Simultaneous editing means two users modifying the same file at once.
        !          19088: Simultaneous editing if not detected can cause one user to lose his
        !          19089: work.  Emacs detects all cases of simultaneous editing and warns the
        !          19090: user to investigate them.  @xref{Interlocking,,Simultaneous Editing}.
        !          19091: 
        !          19092: @need 150
        !          19093: @item String
        !          19094: A string is a kind of Lisp data object which contains a sequence of
        !          19095: characters.  Many Emacs variables are intended to have strings as
        !          19096: values.  The Lisp syntax for a string consists of the characters in
        !          19097: the string with a @samp{"} before and another @samp{"} after.  A
        !          19098: @samp{"} that is part of the string must be written as @samp{\"} and a
        !          19099: @samp{\} that is part of the string must be written as @samp{\\}.  All
        !          19100: other characters, including newline, can be included just by writing
        !          19101: them inside the string; however, escape sequences as in C, such as
        !          19102: @samp{\n} for newline or @samp{\241} using an octal character code,
        !          19103: are allowed as well.
        !          19104: 
        !          19105: @need 150
        !          19106: @item String Substitution
        !          19107: See `global substitution'.
        !          19108: 
        !          19109: @need 150
        !          19110: @item Syntax Table
        !          19111: The syntax table tells Emacs which characters are part of a word,
        !          19112: which characters balance each other like parentheses, etc.
        !          19113: @xref{Syntax}.
        !          19114: 
        !          19115: @need 150
        !          19116: @item Tag Table
        !          19117: A tag table is a file that serves as an index to the function
        !          19118: definitions in one or more other files.  @xref{Tags}.
        !          19119: 
        !          19120: @need 150
        !          19121: @item Termscript File
        !          19122: A termscript file contains a record of all characters sent by Emacs to
        !          19123: the terminal.  It is used for tracking down bugs in Emacs redisplay.
        !          19124: Emacs does not make a termscript file unless you tell it to.
        !          19125: @xref{Bugs}.
        !          19126: 
        !          19127: @need 150
        !          19128: @item Text
        !          19129: Two meanings (@pxref{Text}):
        !          19130: 
        !          19131: @need 150
        !          19132: @itemize @bullet
        !          19133: @need 150
        !          19134: @item
        !          19135: Data consisting of a sequence of characters, as opposed to binary
        !          19136: numbers, images, graphics commands, executable programs, and the like.
        !          19137: The contents of an Emacs buffer are always text in this sense.
        !          19138: @need 150
        !          19139: @item
        !          19140: Data consisting of written human language, as opposed to programs,
        !          19141: or following the stylistic conventions of human language.
        !          19142: @end itemize
        !          19143: 
        !          19144: @need 150
        !          19145: @item Top Level
        !          19146: Top level is the normal state of Emacs, in which you are editing the
        !          19147: text of the file you have visited.  You are at top level whenever you
        !          19148: are not in a recursive editing level (q.v.@:) or the minibuffer
        !          19149: (q.v.@:), and not in the middle of a command.  You can get back to top
        !          19150: level by aborting (q.v.@:) and quitting (q.v.@:).  @xref{Quitting}.
        !          19151: 
        !          19152: @need 150
        !          19153: @item Transposition
        !          19154: Transposing two units of text means putting each one into the place
        !          19155: formerly occupied by the other.  There are Emacs commands to transpose
        !          19156: two adjacent characters, words, sexps (q.v.@:) or lines
        !          19157: (@pxref{Transpose}).
        !          19158: 
        !          19159: @need 150
        !          19160: @item Truncation
        !          19161: Truncating text lines in the display means leaving out any text on a
        !          19162: line that does not fit within the right margin of the window
        !          19163: displaying it.  See also `continuation line'.
        !          19164: @xref{Basic,Truncation,Basic Editing}.
        !          19165: 
        !          19166: @need 150
        !          19167: @item Undoing
        !          19168: Undoing means making your previous editing go in reverse, bringing
        !          19169: back the text that existed earlier in the editing session.
        !          19170: @xref{Undo}.
        !          19171: 
        !          19172: @need 150
        !          19173: @item Variable
        !          19174: A variable is an object in Lisp that can store an arbitrary value.
        !          19175: Emacs uses some variables for internal purposes, and has others (known
        !          19176: as `options' (q.v.@:)) just so that you can set their values to
        !          19177: control the behavior of Emacs.  The variables used in Emacs that you
        !          19178: are likely to be interested in are listed in the Variables Index in
        !          19179: this manual.  @xref{Variables}, for information on variables.
        !          19180: 
        !          19181: @need 150
        !          19182: @item Visiting
        !          19183: Visiting a file means loading its contents into a buffer (q.v.@:)
        !          19184: where they can be edited.  @xref{Visiting}.
        !          19185: 
        !          19186: @need 150
        !          19187: @item Whitespace
        !          19188: Whitespace is any run of consecutive formatting characters (space,
        !          19189: tab, newline, and backspace).
        !          19190: 
        !          19191: @need 150
        !          19192: @item Widening
        !          19193: Widening is removing any restriction (q.v.@:) on the current buffer;
        !          19194: it is the opposite of narrowing (q.v.@:).  @xref{Narrowing}.
        !          19195: 
        !          19196: @need 150
        !          19197: @item Window
        !          19198: Emacs divides the screen into one or more windows, each of which can
        !          19199: display the contents of one buffer (q.v.@:) at any time.
        !          19200: @xref{Screen}, for basic information on how Emacs uses the screen.
        !          19201: @xref{Windows}, for commands to control the use of windows.
        !          19202: 
        !          19203: @need 150
        !          19204: @item Word Abbrev
        !          19205: Synonymous with `abbrev'.
        !          19206: 
        !          19207: @need 150
        !          19208: @item Word Search
        !          19209: Word search is searching for a sequence of words, considering the
        !          19210: punctuation between them as insignificant.  @xref{Word Search}.
        !          19211: 
        !          19212: @need 150
        !          19213: @item Yanking
        !          19214: Yanking means reinserting text previously killed.  It can be used to
        !          19215: undo a mistaken kill, or for copying or moving text.  Some other
        !          19216: systems call this ``pasting''.  @xref{Yanking}.
        !          19217: @end table
        !          19218: 
        !          19219: @node Key Index, Command Index, Glossary, Top
        !          19220: @unnumbered Key (Character) Index
        !          19221: @printindex ky
        !          19222: 
        !          19223: @node Command Index, Variable Index, Key Index, Top
        !          19224: @unnumbered Command and Function Index
        !          19225: @printindex fn
        !          19226: 
        !          19227: @node Variable Index, Concept Index, Command Index, Top
        !          19228: @unnumbered Variable Index
        !          19229: @printindex vr
        !          19230: 
        !          19231: @node Concept Index, Screen, Variable Index, Top
        !          19232: @unnumbered Concept Index
        !          19233: @printindex cp
        !          19234: 
        !          19235: @tex
        !          19236: \global\baselineskip 11.5pt
        !          19237: @end tex
        !          19238: 
        !          19239: @summarycontents
        !          19240: @contents
        !          19241: @bye