Return to emacs-4 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info

Annotation of 43BSDReno/contrib/emacs-18.55/info/emacs-4, revision 1.1

1.1     ! root        1: Info file emacs, produced by texinfo-format-buffer   -*-Text-*-
        !             2: from file emacs.tex
        !             3: 
        !             4: This file documents the GNU Emacs editor.
        !             5: 
        !             6: Copyright (C) 1985, 1986 Richard M. Stallman.
        !             7: 
        !             8: Permission is granted to make and distribute verbatim copies of
        !             9: this manual provided the copyright notice and this permission notice
        !            10: are preserved on all copies.
        !            11: 
        !            12: Permission is granted to copy and distribute modified versions of this
        !            13: manual under the conditions for verbatim copying, provided also that the
        !            14: sections entitled "The GNU Manifesto", "Distribution" and "GNU Emacs
        !            15: General Public License" are included exactly as in the original, and
        !            16: provided that the entire resulting derived work is distributed under the
        !            17: terms of a permission notice identical to this one.
        !            18: 
        !            19: Permission is granted to copy and distribute translations of this manual
        !            20: into another language, under the above conditions for modified versions,
        !            21: except that the sections entitled "The GNU Manifesto", "Distribution"
        !            22: and "GNU Emacs General Public License" may be included in a translation
        !            23: approved by the author instead of in the original English.
        !            24: 
        !            25: 
        !            26: File: emacs  Node: Regexps, Prev: Regexp Search, Up: Search, Next: Search Case
        !            27: 
        !            28: Syntax of Regular Expressions
        !            29: =============================
        !            30: 
        !            31: Regular expressions have a syntax in which a few characters are special
        !            32: constructs and the rest are "ordinary".  An ordinary character is a simple
        !            33: regular expression which matches that character and nothing else.  The
        !            34: special characters are `$', `^', `.', `*', `+', `?', `[', `]' and `\'; no
        !            35: new special characters will be defined.  Any other character appearing in a
        !            36: regular expression is ordinary, unless a `\' precedes it.
        !            37: 
        !            38: For example, `f' is not a special character, so it is ordinary, and
        !            39: therefore `f' is a regular expression that matches the string `f' and no
        !            40: other string.  (It does not match the string `ff'.)  Likewise, `o' is a
        !            41: regular expression that matches only `o'.
        !            42: 
        !            43: Any two regular expressions A and B can be concatenated.  The result is a
        !            44: regular expression which matches a string if A matches some amount of the
        !            45: beginning of that string and B matches the rest of the string.
        !            46: 
        !            47: As a simple example, we can concatenate the regular expressions `f'
        !            48: and `o' to get the regular expression `fo', which matches only
        !            49: the string `fo'.  Still trivial.  To do something nontrivial, you
        !            50: need to use one of the special characters.  Here is a list of them.
        !            51: 
        !            52: `. (Period)'     
        !            53:      is a special character that matches any single character except a
        !            54:      newline.  Using concatenation, we can make regular expressions like
        !            55:      `a.b' which matches any three-character string which begins with `a'
        !            56:      and ends with `b'.
        !            57:      
        !            58: `*'     
        !            59:      is not a construct by itself; it is a suffix, which means the
        !            60:      preceding regular expression is to be repeated as many times as
        !            61:      possible.  In `fo*', the `*' applies to the `o', so `fo*' matches one
        !            62:      `f' followed by any number of `o's.  The case of zero `o's is allowed:
        !            63:      `fo*' does match `f'.
        !            64:      
        !            65:      `*' always applies to the smallest possible preceding expression.
        !            66:      Thus, `fo*' has a repeating `o', not a repeating `fo'.
        !            67:      
        !            68:      The matcher processes a `*' construct by matching, immediately, as
        !            69:      many repetitions as can be found.  Then it continues with the rest of
        !            70:      the pattern.  If that fails, backtracking occurs, discarding some of
        !            71:      the matches of the `*'-modified construct in case that makes it
        !            72:      possible to match the rest of the pattern.  For example, matching
        !            73:      `ca*ar' against the string `caaar', the `a*' first tries to match all
        !            74:      three `a's; but the rest of the pattern is `ar' and there is only `r'
        !            75:      left to match, so this try fails.  The next alternative is for `a*' to
        !            76:      match only two `a's.  With this choice, the rest of the regexp matches
        !            77:      successfully.
        !            78:      
        !            79: `+'     
        !            80:      Is a suffix character similar to `*' except that it requires that the
        !            81:      preceding expression be matched at least once.  So, for example,
        !            82:      `ca+r' will match the strings `car' and `caaaar' but not the string
        !            83:      `cr', whereas `ca*r' would match all three strings.
        !            84:      
        !            85: `?'     
        !            86:      Is a suffix character similar to `*' except that it can match the
        !            87:      preceding expression either once or not at all.  For example,
        !            88:      `ca?r' will match `car' or `cr'; nothing else.
        !            89:      
        !            90: `[ ... ]'     
        !            91:      `[' begins a "character set", which is terminated by a `]'.  In the
        !            92:      simplest case, the characters between the two form the set.  Thus,
        !            93:      `[ad]' matches either one `a' or one `d', and `[ad]*' matches any
        !            94:      string composed of just `a's and `d's (including the empty string),
        !            95:      from which it follows that `c[ad]*r' matches `cr', `car', `cdr',
        !            96:      `caddaar', etc.
        !            97:      
        !            98:      Character ranges can also be included in a character set, by writing
        !            99:      two characters with a `-' between them.  Thus, `[a-z]' matches any
        !           100:      lower-case letter.  Ranges may be intermixed freely with individual
        !           101:      characters, as in `[a-z$%.]', which matches any lower case letter or
        !           102:      `$', `%' or period.
        !           103:      
        !           104:      Note that the usual special characters are not special any more inside
        !           105:      a character set.  A completely different set of special characters
        !           106:      exists inside character sets: `]', `-' and `^'.
        !           107:      
        !           108:      To include a `]' in a character set, you must make it the first
        !           109:      character.  For example, `[]a]' matches `]' or `a'.  To include a `-',
        !           110:      write `---', which is a range containing only `-'.  To include `^',
        !           111:      make it other than the first character in the set.
        !           112:      
        !           113: `[^ ... ]'     
        !           114:      `[^' begins a "complement character set", which matches any character
        !           115:      except the ones specified.  Thus, `[^a-z0-9A-Z]' matches all
        !           116:      characters except letters and digits.
        !           117:      
        !           118:      `^' is not special in a character set unless it is the first
        !           119:      character.  The character following the `^' is treated as if it
        !           120:      were first (`-' and `]' are not special there).
        !           121:      
        !           122:      Note that a complement character set can match a newline, unless
        !           123:      newline is mentioned as one of the characters not to match.
        !           124:      
        !           125: `^'     
        !           126:      is a special character that matches the empty string, but only if at
        !           127:      the beginning of a line in the text being matched.  Otherwise it fails
        !           128:      to match anything.  Thus, `^foo' matches a `foo' which occurs
        !           129:      at the beginning of a line.
        !           130:      
        !           131: `$'     
        !           132:      is similar to `^' but matches only at the end of a line.  Thus,
        !           133:      `xx*$' matches a string of one `x' or more at the end of a line.
        !           134:      
        !           135: `\'     
        !           136:      has two functions: it quotes the special characters (including
        !           137:      `\'), and it introduces additional special constructs.
        !           138:      
        !           139:      Because `\' quotes special characters, `\$' is a regular expression
        !           140:      which matches only `$', and `\[' is a regular expression which matches
        !           141:      only `[', and so on.
        !           142: 
        !           143: Note: for historical compatibility, special characters are treated as
        !           144: ordinary ones if they are in contexts where their special meanings make no
        !           145: sense.  For example, `*foo' treats `*' as ordinary since there is no
        !           146: preceding expression on which the `*' can act.  It is poor practice to
        !           147: depend on this behavior; better to quote the special character anyway,
        !           148: regardless of where is appears.
        !           149: 
        !           150: For the most part, `\' followed by any character matches only
        !           151: that character.  However, there are several exceptions: characters
        !           152: which, when preceded by `\', are special constructs.  Such
        !           153: characters are always ordinary when encountered on their own.  Here
        !           154: is a table of `\' constructs.
        !           155: 
        !           156: `\|'     
        !           157:      specifies an alternative.  Two regular expressions A and B with `\|'
        !           158:      in between form an expression that matches anything that either A or B
        !           159:      will match.
        !           160:      
        !           161:      Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
        !           162:      
        !           163:      `\|' applies to the largest possible surrounding expressions.  Only a
        !           164:      surrounding `\( ... \)' grouping can limit the grouping power of `\|'.
        !           165:      
        !           166:      Full backtracking capability exists to handle multiple uses of `\|'.
        !           167:      
        !           168: `\( ... \)'     
        !           169:      is a grouping construct that serves three purposes:
        !           170:      
        !           171:        1. To enclose a set of `\|' alternatives for other operations.
        !           172:           Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
        !           173:           
        !           174:        2. To enclose a complicated expression for the postfix `*' to
        !           175:           operate on.  Thus, `ba\(na\)*' matches `bananana', etc., with any
        !           176:           (zero or more) number of `na' strings.
        !           177:           
        !           178:        3. To mark a matched substring for future reference.
        !           179:           
        !           180:      
        !           181:      This last application is not a consequence of the idea of a
        !           182:      parenthetical grouping; it is a separate feature which happens to be
        !           183:      assigned as a second meaning to the same `\( ... \)' construct
        !           184:      because there is no conflict in practice between the two meanings.
        !           185:      Here is an explanation of this feature:
        !           186:      
        !           187: `\DIGIT'     
        !           188:      after the end of a `\( ... \)' construct, the matcher remembers the
        !           189:      beginning and end of the text matched by that construct.  Then, later
        !           190:      on in the regular expression, you can use `\' followed by DIGIT to
        !           191:      mean "match the same text matched the DIGIT'th time by the `\( ... \)'
        !           192:      construct."
        !           193:      
        !           194:      The strings matching the first nine `\( ... \)' constructs appearing
        !           195:      in a regular expression are assigned numbers 1 through 9 in order that the
        !           196:      open-parentheses appear in the regular expression.  `\1' through
        !           197:      `\9' may be used to refer to the text matched by the corresponding
        !           198:      `\( ... \)' construct.
        !           199:      
        !           200:      For example, `\(.*\)\1' matches any newline-free string that is
        !           201:      composed of two identical halves.  The `\(.*\)' matches the first
        !           202:      half, which may be anything, but the `\1' that follows must match
        !           203:      the same exact text.
        !           204:      
        !           205: `\`'     
        !           206:      matches the empty string, provided it is at the beginning
        !           207:      of the buffer.
        !           208:      
        !           209: `\''     
        !           210:      matches the empty string, provided it is at the end of
        !           211:      the buffer.
        !           212:      
        !           213: `\b'     
        !           214:      matches the empty string, provided it is at the beginning or end of a
        !           215:      word.  Thus, `\bfoo\b' matches any occurrence of `foo' as a separate
        !           216:      word.  `\bballs?\b' matches `ball' or `balls' as a separate word.
        !           217:      
        !           218: `\B'     
        !           219:      matches the empty string, provided it is not at the beginning or
        !           220:      end of a word.
        !           221:      
        !           222: `\<'     
        !           223:      matches the empty string, provided it is at the beginning of a word.
        !           224:      
        !           225: `\>'     
        !           226:      matches the empty string, provided it is at the end of a word.
        !           227:      
        !           228: `\w'     
        !           229:      matches any word-constituent character.  The editor syntax table
        !           230:      determines which characters these are.
        !           231:      
        !           232: `\W'     
        !           233:      matches any character that is not a word-constituent.
        !           234:      
        !           235: `\sCODE'     
        !           236:      matches any character whose syntax is CODE.  CODE is a character which
        !           237:      represents a syntax code: thus, `w' for word constituent, `-' for
        !           238:      whitespace, `(' for open-parenthesis, etc.  *Note Syntax::.
        !           239:      
        !           240: `\SCODE'     
        !           241:      matches any character whose syntax is not CODE.
        !           242: 
        !           243:   Here is a complicated regexp, used by Emacs to recognize the end of a
        !           244: sentence together with any whitespace that follows.  It is given in Lisp
        !           245: syntax to enable you to distinguish the spaces from the tab characters.  In
        !           246: Lisp syntax, the string constant begins and ends with a double-quote.
        !           247: `\"' stands for a double-quote as part of the regexp, `\\' for a
        !           248: backslash as part of the regexp, `\t' for a tab and `\n' for a
        !           249: newline.
        !           250: 
        !           251:      "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
        !           252: 
        !           253: This contains four parts in succession: a character set matching period,
        !           254: `?' or `!'; a character set matching close-brackets,
        !           255: quotes or parentheses, repeated any number of times; an alternative in
        !           256: backslash-parentheses that matches end-of-line, a tab or two spaces; and a
        !           257: character set matching whitespace characters, repeated any number of times.
        !           258: 
        !           259: 
        !           260: File: emacs  Node: Search Case, Prev: Regexps, Up: Search, Next: Replace
        !           261: 
        !           262: Searching and Case
        !           263: ==================
        !           264: 
        !           265:   All sorts of searches in Emacs normally ignore the case of the text they
        !           266: are searching through; if you specify searching for `FOO', then `Foo' and
        !           267: `foo' are also considered a match.  Regexps, and in particular character
        !           268: sets, are included: `[aB]' would match `a' or `A' or `b' or `B'.
        !           269: 
        !           270:   If you do not want this feature, set the variable `case-fold-search'
        !           271: to `nil'.  Then all letters must match exactly, including case.  This
        !           272: is a per-buffer variable; altering the variable affects only the current
        !           273: buffer, but there is a default value which you can change as well.
        !           274: *Note Locals::.
        !           275: 
        !           276: 
        !           277: File: emacs  Node: Replace, Prev: Search Case, Up: Search, Next: Other Repeating Search
        !           278: 
        !           279: Replacement Commands
        !           280: ====================
        !           281: 
        !           282:   Global search-and-replace operations are not needed as often in Emacs as
        !           283: they are in other editors, but they are available.  In addition to the
        !           284: simple `replace-string' command which is like that found in most
        !           285: editors, there is a `query-replace' command which asks you, for each
        !           286: occurrence of the pattern, whether to replace it.
        !           287: 
        !           288:   The replace commands all replace one string (or regexp) with one
        !           289: replacement string.  It is possible to perform several replacements in
        !           290: parallel using the command `expand-region-abbrevs'.  *Note Expanding Abbrevs::.
        !           291: 
        !           292: * Menu:
        !           293: 
        !           294: * Unconditional Replace::  Replacing all matches for a string.
        !           295: * Regexp Replace::         Replacing all matches for a regexp.
        !           296: * Replacement and Case::   How replacements preserve case of letters.
        !           297: * Query Replace::          How to use querying.
        !           298: 
        !           299: 
        !           300: File: emacs  Node: Unconditional Replace, Prev: Replace, Up: Replace, Next: Regexp Replace
        !           301: 
        !           302: Unconditional Replacement
        !           303: -------------------------
        !           304: 
        !           305: `M-x replace-string RET STRING RET NEWSTRING RET'     
        !           306:      Replace every occurrence of STRING with NEWSTRING.
        !           307: `M-x replace-regexp RET REGEXP RET NEWSTRING RET'     
        !           308:      Replace every match for REGEXP with NEWSTRING.
        !           309: 
        !           310:   To replace every instance of `foo' after point with `bar', use
        !           311: the command `M-x replace-string' with the two arguments `foo' and
        !           312: `bar'.  Replacement occurs only after point, so if you want to cover
        !           313: the whole buffer you must go to the beginning first.  All occurrences up to
        !           314: the end of the buffer are replaced; to limit replacement to part of the
        !           315: buffer, narrow to that part of the buffer before doing the replacement
        !           316: (*Note Narrowing::).
        !           317: 
        !           318:   When `replace-string' exits, point is left at the last occurrence
        !           319: replaced.  The value of point when the `replace-string' command was
        !           320: issued is remembered on the mark ring; `C-u C-SPC' moves back
        !           321: there.
        !           322: 
        !           323:   A numeric argument restricts replacement to matches that are surrounded
        !           324: by word boundaries.
        !           325: 
        !           326: 
        !           327: File: emacs  Node: Regexp Replace, Prev: Unconditional Replace, Up: Replace, Next: Replacement and Case
        !           328: 
        !           329: Regexp Replacement
        !           330: ------------------
        !           331: 
        !           332:   `replace-string' replaces exact matches for a single string.  The
        !           333: similar command `replace-regexp' replaces any match for a specified
        !           334: pattern.
        !           335: 
        !           336:   In `replace-regexp', the NEWSTRING need not be constant.  It can refer to
        !           337: all or part of what is matched by the REGEXP.  `\&' in NEWSTRING stands for
        !           338: the entire text being replaced.  `\D' in NEWSTRING, where D is a digit,
        !           339: stands for whatever matched the D'th parenthesized grouping in REGEXP.  For
        !           340: example,
        !           341: 
        !           342:      M-x replace-regexp RET c[ad]+r RET \&-safe RET
        !           343: 
        !           344: would replace (for example) `cadr' with `cadr-safe' and `cddr'
        !           345: with `cddr-safe'.
        !           346: 
        !           347:      M-x replace-regexp RET \(c[ad]+r\)-safe RET \1 RET
        !           348: 
        !           349: would perform exactly the opposite replacements.  To include a `\'
        !           350: in the text to replace with, you must give `\\'.
        !           351: 
        !           352: 
        !           353: File: emacs  Node: Replacement and Case, Prev: Regexp Replace, Up: Replace, Next: Query Replace
        !           354: 
        !           355: Replace Commands and Case
        !           356: -------------------------
        !           357: 
        !           358:   If the arguments to a replace command are in lower case, it preserves
        !           359: case when it makes a replacement.  Thus, the command
        !           360: 
        !           361:      M-x replace-string RET foo RET bar RET
        !           362: 
        !           363: replaces a lower case `foo' with a lower case `bar', `FOO'
        !           364: with `BAR', and `Foo' with `Bar'.  If upper case letters are
        !           365: used in the second argument, they remain upper case every time that
        !           366: argument is inserted.  If upper case letters are used in the first
        !           367: argument, the second argument is always substituted exactly as given, with
        !           368: no case conversion.  Likewise, if the variable `case-replace' is set
        !           369: to `nil', replacement is done without case conversion.  If
        !           370: `case-fold-search' is set to `nil', case is significant in
        !           371: matching occurrences of `foo' to replace; also, case conversion of the
        !           372: replacement string is not done.
        !           373: 
        !           374: 
        !           375: File: emacs  Node: Query Replace, Prev: Replacement and Case, Up: Replace
        !           376: 
        !           377: Query Replace
        !           378: -------------
        !           379: 
        !           380: `M-% STRING RET NEWSTRING RET'     
        !           381: `M-x query-replace RET STRING RET NEWSTRING RET'     
        !           382:      Replace some occurrences of STRING with NEWSTRING.
        !           383: `M-x query-replace-regexp RET REGEXP RET NEWSTRING RET'     
        !           384:      Replace some matches for REGEXP with NEWSTRING.
        !           385: 
        !           386:   If you want to change only some of the occurrences of `foo' to `bar', not
        !           387: all of them, then you cannot use an ordinary `replace-string'.  Instead,
        !           388: use `M-%' (`query-replace').  This command finds occurrences of `foo' one
        !           389: by one, displays each occurrence and asks you whether to replace it.  A
        !           390: numeric argument to `query-replace' tells it to consider only occurrences
        !           391: that are bounded by word-delimiter characters.
        !           392: 
        !           393:   Aside from querying, `query-replace' works just like `replace-string',
        !           394: and `query-replace-regexp' works just like `replace-regexp'.
        !           395: 
        !           396:   The things you can type when you are shown an occurrence of STRING
        !           397: or a match for REGEXP are:
        !           398: 
        !           399: 
        !           400: `SPC'     
        !           401:      to replace the occurrence with NEWSTRING.  This preserves case, just
        !           402:      like `replace-string', provided `case-replace' is non-`nil', as it
        !           403:      normally is.
        !           404:      
        !           405: `DEL'     
        !           406:      to skip to the next occurrence without replacing this one.
        !           407:      
        !           408: `, (Comma)'     
        !           409:      to replace this occurrence and display the result.  You are then asked
        !           410:      for another input character, except that since the replacement has
        !           411:      already been made, DEL and SPC are equivalent.  You could
        !           412:      type `C-r' at this point (see below) to alter the replaced text.  You
        !           413:      could also type `C-x u' to undo the replacement; this exits the
        !           414:      `query-replace', so if you want to do further replacement you must use
        !           415:      `C-x ESC' to restart (*Note Repetition::).
        !           416:      
        !           417: `ESC'     
        !           418:      to exit without doing any more replacements.
        !           419:      
        !           420: `. (Period)'     
        !           421:      to replace this occurrence and then exit.
        !           422:      
        !           423: `!'     
        !           424:      to replace all remaining occurrences without asking again.
        !           425:      
        !           426: `^'     
        !           427:      to go back to the location of the previous occurrence (or what used to
        !           428:      be an occurrence), in case you changed it by mistake.  This works by
        !           429:      popping the mark ring.  Only one `^' in a row is allowed, because
        !           430:      only one previous replacement location is kept during `query-replace'.
        !           431:      
        !           432: `C-r'     
        !           433:      to enter a recursive editing level, in case the occurrence needs to be
        !           434:      edited rather than just replaced with NEWSTRING.  When you are
        !           435:      done, exit the recursive editing level with `C-M-c' and the next
        !           436:      occurrence will be displayed.  *Note Recursive Edit::.
        !           437:      
        !           438: `C-w'     
        !           439:      to delete the occurrence, and then enter a recursive editing level as
        !           440:      in `C-r'.  Use the recursive edit to insert text to replace the
        !           441:      deleted occurrence of STRING.  When done, exit the recursive
        !           442:      editing level with `C-M-c' and the next occurrence will be
        !           443:      displayed.
        !           444:      
        !           445: `C-l'     
        !           446:      to redisplay the screen and then give another answer.
        !           447:      
        !           448: `C-h'     
        !           449:      to display a message summarizing these options, then give another
        !           450:      answer.
        !           451: 
        !           452:   If you type any other character, the `query-replace' is exited, and
        !           453: the character executed as a command.  To restart the `query-replace',
        !           454: use `C-x ESC', which repeats the `query-replace' because it
        !           455: used the minibuffer to read its arguments.  *Note C-x ESC: Repetition.
        !           456:   
        !           457: 
        !           458: File: emacs  Node: Other Repeating Search, Prev: Replace, Up: Search
        !           459: 
        !           460: Other Search-and-Loop Commands
        !           461: ==============================
        !           462: 
        !           463:   Here are some other commands that find matches for a regular expression.
        !           464: They all operate from point to the end of the buffer.
        !           465: 
        !           466: `M-x occur'     
        !           467:      Print each line that follows point and contains a match for the
        !           468:      specified regexp.  A numeric argument specifies the number of context
        !           469:      lines to print before and after each matching line; the default is
        !           470:      none.
        !           471:      
        !           472:      The buffer `*Occur*' containing the output serves as a menu for
        !           473:      finding the occurrences in their original context.  Find an occurrence
        !           474:      as listed in `*Occur*', position point there and type `C-c
        !           475:      C-c'; this switches to the buffer that was searched and moves point to
        !           476:      the original of the same occurrence.
        !           477:      
        !           478: `M-x list-matching-lines'     
        !           479:      Synonym for `M-x occur'.
        !           480:      
        !           481: `M-x count-matches'     
        !           482:      Print the number of matches following point for the specified regexp.
        !           483:      
        !           484: `M-x delete-non-matching-lines'     
        !           485:      Delete each line that follows point and does not contain a match for
        !           486:      the specified regexp.
        !           487:      
        !           488: `M-x delete-matching-lines'     
        !           489:      Delete each line that follows point and contains a match for the
        !           490:      specified regexp.
        !           491: 
        !           492: 
        !           493: File: emacs  Node: Fixit, Prev: Search, Up: Top, Next: Files
        !           494: 
        !           495: Commands for Fixing Typos
        !           496: *************************
        !           497: 
        !           498:   In this chapter we describe the commands that are especially useful for
        !           499: the times when you catch a mistake in your text just after you have made
        !           500: it, or change your mind while composing text on line.
        !           501: 
        !           502: * Menu:
        !           503: 
        !           504: * Kill Errors:: Commands to kill a batch of recently entered text.
        !           505: * Transpose::   Exchanging two characters, words, lines, lists...
        !           506: * Fixing Case:: Correcting case of last word entered.
        !           507: * Spelling::    Apply spelling checker to a word, or a whole file.
        !           508: 
        !           509: 
        !           510: File: emacs  Node: Kill Errors, Prev: Fixit, Up: Fixit, Next: Transpose
        !           511: 
        !           512: Killing Your Mistakes
        !           513: =====================
        !           514: 
        !           515: `DEL'     
        !           516:      Delete last character (`delete-backward-char').
        !           517: `M-DEL'     
        !           518:      Kill last word (`backward-kill-word').
        !           519: `C-x DEL'     
        !           520:      Kill to beginning of sentence (`backward-kill-sentence').
        !           521: 
        !           522:   The DEL character (`delete-backward-char') is the most
        !           523: important correction command.  When used among graphic (self-inserting)
        !           524: characters, it can be thought of as canceling the last character typed.
        !           525: 
        !           526:   When your mistake is longer than a couple of characters, it might be more
        !           527: convenient to use `M-DEL' or `C-x DEL'.  `M-DEL' kills back to the start of
        !           528: the last word, and `C-x DEL' kills back to the start of the last sentence.
        !           529: `C-x DEL' is particularly useful when you are thinking of what to write as
        !           530: you type it, in case you change your mind about phrasing.  `M-DEL' and `C-x
        !           531: DEL' save the killed text for `C-y' and `M-y' to retrieve.  *Note
        !           532: Yanking::.
        !           533: 
        !           534:   `M-DEL' is often useful even when you have typed only a few
        !           535: characters wrong, if you know you are confused in your typing and aren't
        !           536: sure exactly what you typed.  At such a time, you cannot correct with
        !           537: DEL except by looking at the screen to see what you did.  It requires
        !           538: less thought to kill the whole word and start over again.
        !           539: 
        !           540: 
        !           541: File: emacs  Node: Transpose, Prev: Kill Errors, Up: Fixit, Next: Fixing Case
        !           542: 
        !           543: Transposing Text
        !           544: ================
        !           545: 
        !           546: `C-t'     
        !           547:      Transpose two characters (`transpose-chars').
        !           548: `M-t'     
        !           549:      Transpose two words (`transpose-words').
        !           550: `C-M-t'     
        !           551:      Transpose two balanced expressions (`transpose-sexps').
        !           552: `C-x C-t'     
        !           553:      Transpose two lines (`transpose-lines').
        !           554: 
        !           555:   The common error of transposing two characters can be fixed, when they
        !           556: are adjacent, with the `C-t' command (`transpose-chars').  Normally,
        !           557: `C-t' transposes the two characters on either side of point.  When
        !           558: given at the end of a line, rather than transposing the last character of
        !           559: the line with the newline, which would be useless, `C-t' transposes the
        !           560: last two characters on the line.  So, if you catch your transposition error
        !           561: right away, you can fix it with just a `C-t'.  If you don't catch it so
        !           562: fast, you must move the cursor back to between the two transposed
        !           563: characters.  If you transposed a space with the last character of the word
        !           564: before it, the word motion commands are a good way of getting there.
        !           565: Otherwise, a reverse search (`C-r') is often the best way.
        !           566: *Note Search::.
        !           567: 
        !           568: 
        !           569:   `Meta-t' (`transpose-words') transposes the word before point
        !           570: with the word after point.  It moves point forward over a word, dragging
        !           571: the word preceding or containing point forward as well.  The punctuation
        !           572: characters between the words do not move.  For example, `FOO, BAR'
        !           573: transposes into `BAR, FOO' rather than `BAR FOO,'.
        !           574: 
        !           575:   `C-M-t' (`transpose-sexps') is a similar command for transposing
        !           576: two expressions (*Note Lists::), and `{C-x C-t} (`transpose-lines')'exchanges lines.  They work like `M-t' except in determining the
        !           577: division of the text into syntactic units.
        !           578: 
        !           579:   A numeric argument to a transpose command serves as a repeat count: it
        !           580: tells the transpose command to move the character (word, sexp, line) before
        !           581: or containing point across several other characters (words, sexps, lines).
        !           582: For example, `C-u 3 C-t' moves the character before point forward across
        !           583: three other characters.  This is equivalent to repeating `C-t' three times.
        !           584: `C-u - 4 M-t' moves the word before point backward across four words.  `C-u
        !           585: - C-M-t' would cancel the effect of plain `C-M-t'.
        !           586: 
        !           587:   A numeric argument of zero is assigned a special meaning (because
        !           588: otherwise a command with a repeat count of zero would do nothing): to
        !           589: transpose the character (word, sexp, line) ending after point with the
        !           590: one ending after the mark.
        !           591: 
        !           592: 
        !           593: File: emacs  Node: Fixing Case, Prev: Transpose, Up: Fixit, Next: Spelling
        !           594: 
        !           595: Case Conversion
        !           596: ===============
        !           597: 
        !           598: `M-- M-l'     
        !           599:      Convert last word to lower case.  Note `Meta--' is Meta-minus.
        !           600: `M-- M-u'     
        !           601:      Convert last word to all upper case.
        !           602: `M-- M-c'     
        !           603:      Convert last word to lower case with capital initial.
        !           604: 
        !           605:   A very common error is to type words in the wrong case.  Because of this,
        !           606: the word case-conversion commands `M-l', `M-u' and `M-c' have a special
        !           607: feature when used with a negative argument: they do not move the cursor.
        !           608: As soon as you see you have mistyped the last word, you can simply
        !           609: case-convert it and go on typing.  *Note Case::.
        !           610: 
        !           611: 
        !           612: File: emacs  Node: Spelling, Prev: Fixing Case, Up: Fixit
        !           613: 
        !           614: Checking and Correcting Spelling
        !           615: ================================
        !           616: 
        !           617: `M-$'     
        !           618:      Check and correct spelling of word (`spell-word').
        !           619: `M-x spell-buffer'     
        !           620:      Check and correct spelling of each word in the buffer.
        !           621: `M-x spell-region'     
        !           622:      Check and correct spelling of each word in the region.
        !           623: `M-x spell-string'     
        !           624:      Check spelling of specified word.
        !           625: 
        !           626:   To check the spelling of the word before point, and optionally correct it
        !           627: as well, use the command `M-$' (`spell-word').  This command runs
        !           628: an inferior process containing the `spell' program to see whether the
        !           629: word is correct English.  If it is not, it asks you to edit the word (in
        !           630: the minibuffer) into a corrected spelling, and then does a `query-replace'
        !           631: to substitute the corrected spelling for the old one throughout the buffer.
        !           632: 
        !           633:   If you exit the minibuffer without altering the original spelling, it
        !           634: means you do not want to do anything to that word.  Then the `query-replace'
        !           635: is not done.
        !           636: 
        !           637:   `M-x spell-buffer' checks each word in the buffer the same way that
        !           638: `spell-word' does, doing a `query-replace' if appropriate for every
        !           639: incorrect word.
        !           640: 
        !           641:   `M-x spell-region' is similar but operates only on the region, not
        !           642: the entire buffer.
        !           643: 
        !           644:   `M-x spell-string' reads a string as an argument and checks whether
        !           645: that is a correctly spelled English word.  It prints in the echo area a
        !           646: message giving the answer.
        !           647: 
        !           648: 
        !           649: File: emacs  Node: Files, Prev: Fixit, Up: Top, Next: Buffers
        !           650: 
        !           651: File Handling
        !           652: *************
        !           653: 
        !           654:   The basic unit of stored data in Unix is the "file".  To edit a file,
        !           655: you must tell Emacs to examine the file and prepare a buffer containing a
        !           656: copy of the file's text.  This is called "visiting" the file.  Editing
        !           657: commands apply directly to text in the buffer; that is, to the copy inside
        !           658: Emacs.  Your changes appear in the file itself only when you "save" the
        !           659: buffer back into the file.
        !           660: 
        !           661:   In addition to visiting and saving files, Emacs can delete, copy, rename,
        !           662: and append to files, and operate on file directories.
        !           663: 
        !           664: * Menu:
        !           665: 
        !           666: * File Names::   How to type and edit file name arguments.
        !           667: * Visiting::     Visiting a file prepares Emacs to edit the file.
        !           668: * Saving::       Saving makes your changes permanent.
        !           669: * Reverting::    Reverting cancels all the changes not saved.
        !           670: * Auto Save::    Auto Save periodically protects against loss of data.
        !           671: * ListDir::      Listing the contents of a file directory.
        !           672: * Dired::        "Editing" a directory to delete, rename, etc.
        !           673:                   the files in it.
        !           674: * Misc File Ops:: Other things you can do on files.
        !           675: 
        !           676: 
        !           677: File: emacs  Node: File Names, Prev: Files, Up: Files, Next: Visiting
        !           678: 
        !           679: File Names
        !           680: ==========
        !           681: 
        !           682:   Most Emacs commands that operate on a file require you to specify the
        !           683: file name.  (Saving and reverting are exceptions; the buffer knows which
        !           684: file name to use for them.)  File names are specified using the minibuffer
        !           685: (*Note Minibuffer::).  "Completion" is available, to make it easier to
        !           686: specify long file names.  *Note Completion::.
        !           687: 
        !           688:   There is always a "default file name" which will be used if you type
        !           689: just RET, entering an empty argument.  Normally the default file name
        !           690: is the name of the file visited in the current buffer; this makes it easy
        !           691: to operate on that file with any of the Emacs file commands.
        !           692: 
        !           693:   Each buffer has a default directory, normally the same as the directory
        !           694: of the file visited in that buffer.  When Emacs reads a file name, if you
        !           695: do not specify a directory, the default directory is used.  If you specify
        !           696: a directory in a relative fashion, with a name that does not start with a
        !           697: slash, it is interpreted with respect to the default directory.  The
        !           698: default directory is kept in the variable `default-directory', which
        !           699: has a separate value in every buffer.
        !           700: 
        !           701:   For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
        !           702: the default directory is `/u/rms/gnu/'.  If you type just `foo',
        !           703: which does not specify a directory, it is short for `/u/rms/gnu/foo'.
        !           704: `../.login' would stand for `/u/rms/.login'.  `new/foo'
        !           705: would stand for the filename `/u/rms/gnu/new/foo'.
        !           706: 
        !           707:   The command `M-x pwd' prints the current buffer's default directory,
        !           708: and the command `M-x cd' sets it (to a value read using the
        !           709: minibuffer).  A buffer's default directory changes only when the `cd'
        !           710: command is used.  A file-visiting buffer's default directory is initialized
        !           711: to the directory of the file that is visited there.  If a buffer is made
        !           712: randomly with `C-x b', its default directory is copied from that of the
        !           713: buffer that was current at the time.
        !           714: 
        !           715:   The default directory actually appears in the minibuffer when the
        !           716: minibuffer becomes active to read a file name.  This serves two purposes:
        !           717: it shows you what the default is, so that you can type a relative file name
        !           718: and know with certainty what it will mean, and it allows you to edit the
        !           719: default to specify a different directory.  This insertion of the default
        !           720: directory is inhibited if the variable `insert-default-directory' is
        !           721: set to `nil'.
        !           722: 
        !           723:   Note that it is legitimate to type an absolute file name after you enter
        !           724: the minibuffer, ignoring the presence of the default directory name as part
        !           725: of the text.  The final minibuffer contents may look invalid, but that is
        !           726: not so.  *Note Minibuffer File::.
        !           727: 
        !           728:   `$' in a file name is used to substitute environment variables.  For
        !           729: example, if you have used the shell command `setenv FOO rms/hacks' to
        !           730: set up an environment variable named `FOO', then you can use
        !           731: `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
        !           732: `/u/rms/hacks/test.c'.  The environment variable name consists of all
        !           733: the alphanumeric characters after the `$'; alternatively, it may be
        !           734: enclosed in braces after the `$'.  Note that the `setenv' command
        !           735: affects Emacs only if done before Emacs is started.
        !           736: 
        !           737:   To access a file with `$' in its name, type `$$'.  This pair
        !           738: is converted to a single `$' at the same time as variable substitution
        !           739: is performed for single `$'.  The Lisp function that performs the
        !           740: substitution is called `substitute-in-file-name'.  The substitution
        !           741: is performed only on filenames read as such using the minibuffer.
        !           742: 
        !           743: 
        !           744: File: emacs  Node: Visiting, Prev: File Names, Up: Files, Next: Saving
        !           745: 
        !           746: Visiting Files
        !           747: ==============
        !           748: 
        !           749: `C-x C-f'     
        !           750:      Visit a file (`find-file').
        !           751: `C-x C-v'     
        !           752:      Visit a different file instead of the one visited last
        !           753:      (`find-alternate-file').
        !           754: `C-x 4 C-f'     
        !           755:      Visit a file, in another window (`find-file-other-window').  Don't
        !           756:      change this window.
        !           757: 
        !           758:   "Visiting" a file means copying its contents into Emacs where you can
        !           759: edit them.  Emacs makes a new buffer for each file that you visit.  We say
        !           760: that the buffer is visiting the file that it was created to hold.  Emacs
        !           761: constructs the buffer name from the file name by throwing away the
        !           762: directory, keeping just the name proper.  For example, a file named
        !           763: `/usr/rms/emacs.tex' would get a buffer named `emacs.tex'.  If
        !           764: there is already a buffer with that name, a unique name is constructed by
        !           765: appending `<2>', `<3>', or so on, using the lowest number that
        !           766: makes a name that is not already in use.
        !           767: 
        !           768:   Each window's mode line shows the name of the buffer that is being displayed
        !           769: in that window, so you can always tell what buffer you are editing.
        !           770: 
        !           771:   The changes you make with Emacs are made in the Emacs buffer.  They do
        !           772: not take effect in the file that you visited, or any place permanent, until
        !           773: you "save" the buffer.  Saving the buffer means that Emacs writes the
        !           774: current contents of the buffer into its visited file.  *Note Saving::.
        !           775: 
        !           776:   If a buffer contains changes that have not been saved, the buffer is said
        !           777: to be "modified".  This is important because it implies that some
        !           778: changes will be lost if the buffer is not saved.  The mode line displays
        !           779: two stars near the left margin if the buffer is modified.
        !           780: 
        !           781:   To visit a file, use the command `C-x C-f' (`find-file').  Follow
        !           782: the command with the name of the file you wish to visit, terminated by a
        !           783: RET.
        !           784: 
        !           785:   The file name is read using the minibuffer (*Note Minibuffer::), with
        !           786: defaulting and completion in the standard manner (*Note File Names::).
        !           787: While in the minibuffer, you can abort `C-x C-f' by typing `C-g'.
        !           788: 
        !           789:   Your confirmation that `C-x C-f' has completed successfully is the
        !           790: appearance of new text on the screen and a new buffer name in the mode
        !           791: line.  If the specified file does not exist and could not be created, or
        !           792: cannot be read, then an error results.  The error message is printed in the
        !           793: echo area, and includes the file name which Emacs was trying to visit.
        !           794: 
        !           795:   If you visit a file that is already in Emacs, `C-x C-f' does not make
        !           796: another copy.  It selects the existing buffer containing that file.
        !           797: However, before doing so, it checks that the file itself has not changed
        !           798: since you visited or saved it last.  If the file has changed, a warning
        !           799: message is printed.  *Note Simultaneous Editing: Interlocking.
        !           800: 
        !           801:   What if you want to create a file?  Just visit it.  Emacs prints
        !           802: `(New File)' in the echo area, but in other respects behaves as if you
        !           803: had visited an existing empty file.  If you make any changes and save them,
        !           804: the file is created.
        !           805: 
        !           806:   If you visit a nonexistent file unintentionally (because you typed the
        !           807: wrong file name), use the `C-x C-v' (`find-alternate-file')
        !           808: command to visit the file you wanted.  `C-x C-v' is similar to `C-x
        !           809: C-f', but it kills the current buffer (after first offering to save it if
        !           810: it is modified).  `C-x C-v' is allowed even if the current buffer
        !           811: is not visiting a file.
        !           812: 
        !           813:   If the file you specify is actually a directory, Dired is called on that
        !           814: directory (*Note Dired::).  This can be inhibited by setting the variable
        !           815: `find-file-run-dired' to `nil'; then it is an error to try to
        !           816: visit a directory.
        !           817: 
        !           818:   `C-x 4 f' (`find-file-other-window') is like `C-x C-f'
        !           819: except that the buffer containing the specified file is selected in another
        !           820: window.  The window that was selected before `C-x 4 f' continues to
        !           821: show the same buffer it was already showing.  If this command is used when
        !           822: only one window is being displayed, that window is split in two, with one
        !           823: window showing the same before as before, and the other one showing the
        !           824: newly requested file.  *Note Windows::.
        !           825: 
        !           826:   There are two hook variables that allow extensions to modify the
        !           827: operation of visiting files.  Visiting a file that does not exist runs the
        !           828: functions in the list `find-file-not-found-hooks'; the value of this
        !           829: variable is expected to be a list of functions, and the functions are
        !           830: called one by one until one of them returns non-`nil'.  Any visiting
        !           831: of a file, whether extant or not, expects `find-file-hooks' to
        !           832: contain list of functions and calls them all, one by one.  In both cases
        !           833: the functions receive no arguments.  Visiting a nonexistent file
        !           834: runs the `find-file-not-found-hooks' first.
        !           835: 
        !           836: 
        !           837: File: emacs  Node: Saving, Prev: Visiting, Up: Files, Next: Reverting
        !           838: 
        !           839: Saving Files
        !           840: ============
        !           841: 
        !           842:   "Saving" a buffer in Emacs means writing its contents back into the file
        !           843: that was visited in the buffer.
        !           844: 
        !           845: `C-x C-s'     
        !           846:      Save the current buffer in its visited file (`save-buffer').
        !           847: `C-x s'     
        !           848:      Save any or all buffers in their visited files (`save-some-buffers').
        !           849: `M-~'     
        !           850:      Forget that the current buffer has been changed (`not-modified').
        !           851: `C-x C-w'     
        !           852:      Save the current buffer in a specified file, and record that file as
        !           853:      the one visited in the buffer (`write-file').
        !           854: `M-x set-visited-file-name'     
        !           855:      Change file the name under which the current buffer will be saved.
        !           856: 
        !           857:   When you wish to save the file and make your changes permanent, type
        !           858: `C-x C-s' (`save-buffer').  After saving is finished, `C-x C-s'
        !           859: prints a message such as
        !           860: 
        !           861:      Wrote /u/rms/gnu/gnu.tasks
        !           862: 
        !           863: If the selected buffer is not modified (no changes have been made in it
        !           864: since the buffer was created or last saved), saving is not really done,
        !           865: because it would have no effect.  Instead, `C-x C-s' prints a message
        !           866: in the echo area saying
        !           867: 
        !           868:      (No changes need to be written)
        !           869: 
        !           870:   The command `C-x s' (`save-some-buffers') can save any or all modified
        !           871: buffers.  First it asks, for each modified buffer, whether to save it.
        !           872: These questions should be answered with `y' or `n'.  `C-x C-c',
        !           873: the key that kills Emacs, invokes `save-some-buffers' and therefore
        !           874: asks the same questions.
        !           875: 
        !           876:   If you have changed a buffer and do not want the changes to be saved, you
        !           877: should take some action to prevent it.  Otherwise, each time you use
        !           878: `save-some-buffers' you are liable to save it by mistake.  One thing
        !           879: you can do is type `M-~' (`not-modified'), which clears out the
        !           880: indication that the buffer is modified.  If you do this, none of the save
        !           881: commands will believe that the buffer needs to be saved.  (`~' is often
        !           882: used as a mathematical symbol for `not'; thus `Meta-~' is `not', metafied.)
        !           883: You could also use `set-visited-file-name' (see below) to mark the
        !           884: buffer as visiting a different file name, one which is not in use for
        !           885: anything important.  Alternatively, you can undo all the changes made since
        !           886: the file was visited or saved, by reading the text from the file again.
        !           887: This is called "reverting".  *Note Reverting::.  You could also undo all
        !           888: the changes by repeating the undo command `C-x u' until you have undone
        !           889: all the changes; but this only works if you have not made more changes than
        !           890: the undo mechanism can remember.
        !           891: 
        !           892:   `M-x set-visited-file-name' alters the name of the file that the
        !           893: current buffer is visiting.  It reads the new file name using the
        !           894: minibuffer.  It can be used on a buffer that is not visiting a file, too.
        !           895: The buffer's name is changed to correspond to the file it is now visiting
        !           896: in the usual fashion (unless the new name is in use already for some other
        !           897: buffer; in that case, the buffer name is not changed).
        !           898: `set-visited-file-name' does not save the buffer in the newly visited
        !           899: file; it just alters the records inside Emacs so that, if you save the
        !           900: buffer, it will be saved in that file.  It also marks the buffer as
        !           901: "modified" so that `C-x C-s' will save.
        !           902: 
        !           903:   If you wish to mark the buffer as visiting a different file and save it
        !           904: right away, use `C-x C-w' (`write-file').  It is precisely
        !           905: equivalent to `set-visited-file-name' followed by `C-x C-s'.
        !           906: `C-x C-s' used on a buffer that is not visiting with a file has the
        !           907: same effect as `C-x C-w'; that is, it reads a file name, marks the
        !           908: buffer as visiting that file, and saves it there.  The default file name in
        !           909: a buffer that is not visiting a file is made by combining the buffer name
        !           910: with the buffer's default directory.
        !           911: 
        !           912:   If Emacs is about to save a file and sees that the date of the latest
        !           913: version on disk does not match what Emacs last read or wrote, Emacs
        !           914: notifies you of this fact, because it probably indicates a problem caused
        !           915: by simultaneous editing and requires your immediate attention.
        !           916: *Note Simultaneous Editing: Interlocking.
        !           917: 
        !           918:   If the variable `require-final-newline' is non-`nil', Emacs
        !           919: puts a newline at the end of any file that doesn't already end in one,
        !           920: every time a file is saved or written.
        !           921: 
        !           922:   You can implement other ways to write files, and other things to be done
        !           923: before writing them, using the hook variable `write-file-hooks'.  The
        !           924: value of this variable should be a list of Lisp functions.  When a file is
        !           925: to be written, the functions in the list are called, one by one, with no
        !           926: arguments.  If one of them returns a non-`nil' value, Emacs takes this
        !           927: to mean that the file has been written in some suitable fashion; the rest
        !           928: of the functions are not called, and normal writing is not done.
        !           929: 
        !           930: * Menu:
        !           931: 
        !           932: * Backup::       How Emacs saves the old version of your file.
        !           933: * Interlocking:: How Emacs protects against simultaneous editing
        !           934:                   of one file by two users.
        !           935: 
        !           936: 
        !           937: File: emacs  Node: Backup, Prev: Saving, Up: Saving, Next: Interlocking
        !           938: 
        !           939: Backup Files
        !           940: ------------
        !           941: 
        !           942:   Because Unix does not provide version numbers in file names, rewriting a
        !           943: file in Unix automatically destroys all record of what the file used to
        !           944: contain.  Thus, saving a file from Emacs throws away the old contents of
        !           945: the file---or it would, except that Emacs carefully copies the old contents
        !           946: to another file, called the "backup" file, before actually saving.
        !           947: (Provided the variable `make-backup-files' is non-`nil'.
        !           948: Backup files are not written if this variable is `nil').
        !           949: 
        !           950:   At your option, Emacs can keep either a single backup file or a series of
        !           951: numbered backup files for each file that you edit.
        !           952: 
        !           953:   Emacs makes a backup for a file only the first time the file is saved
        !           954: from one buffer.  No matter how many times you save a file, its backup file
        !           955: continues to contain the contents from before the file was visited.
        !           956: Normally this means that the backup file contains the contents from before
        !           957: the current editing session; however, if you kill the buffer and then visit
        !           958: the file again, a new backup file will be made by the next save.
        !           959: 
        !           960: * Menu:
        !           961: 
        !           962: * Names: Backup Names.         How backup files are named;
        !           963:                                Choosing single or numbered backup files.
        !           964: * Deletion: Backup Deletion.   Emacs deletes excess numbered backups.
        !           965: * Copying: Backup Copying.     Backups can be made by copying or renaming.
        !           966: 
        !           967: 
        !           968: File: emacs  Node: Backup Names, Prev: Backup, Up: Backup, Next: Backup Deletion
        !           969: 
        !           970: Single or Numbered Backups
        !           971: ..........................
        !           972: 
        !           973:   If you choose to have a single backup file (this is the default),
        !           974: the backup file's name is constructed by appending `~' to the
        !           975: file name being edited; thus, the backup file for `eval.c' would
        !           976: be `eval.c~'.
        !           977: 
        !           978:   If you choose to have a series of numbered backup files, backup file
        !           979: names are made by appending `.~', the number, and another `~' to
        !           980: the original file name.  Thus, the backup files of `eval.c' would be
        !           981: called `eval.c.~1~', `eval.c.~2~', and so on, through names
        !           982: like `eval.c.~259~' and beyond.
        !           983: 
        !           984:   If protection stops you from writing backup files under the usual names,
        !           985: the backup file is written as `%backup%~' in your home directory.
        !           986: Only one such file can exist, so only the most recently made such backup is
        !           987: available.
        !           988: 
        !           989:   The choice of single backup or numbered backups is controlled by the
        !           990: variable `version-control'.  Its possible values are
        !           991: 
        !           992: `t'     
        !           993:      Make numbered backups.
        !           994: `nil'     
        !           995:      Make numbered backups for files that have numbered backups already.
        !           996:      Otherwise, make single backups.
        !           997: `never'     
        !           998:      Do not in any case make numbered backups; always make single backups.
        !           999: 
        !          1000: `version-control' may be set locally in an individual buffer to
        !          1001: control the making of backups for that buffer's file.  For example,
        !          1002: Rmail mode locally sets `version-control' to `never' to make sure
        !          1003: that there is only one backup for an Rmail file.  *Note Locals::.
        !          1004: 
        !          1005: 
        !          1006: File: emacs  Node: Backup Deletion, Prev: Backup Names, Up: Backup, Next: Backup Copying
        !          1007: 
        !          1008: Automatic Deletion of Backups
        !          1009: .............................
        !          1010: 
        !          1011:   To prevent unlimited consumption of disk space, Emacs can delete numbered
        !          1012: backup versions automatically.  Generally Emacs keeps the first few backups
        !          1013: and the latest few backups, deleting any in between.  This happens every
        !          1014: time a new backup is made.  The two variables that control the deletion are
        !          1015: `kept-old-versions' and `kept-new-versions'.  Their values are, respectively
        !          1016: the number of oldest (lowest-numbered) backups to keep and the number of
        !          1017: newest (highest-numbered) ones to keep, each time a new backup is made.
        !          1018: Recall that these values are used just after a new backup version is made;
        !          1019: that newly made backup is included in the count in `kept-new-versions'.
        !          1020: By default, both variables are 2.
        !          1021: 
        !          1022:   If `trim-versions-without-asking' is non-`nil', the excess
        !          1023: middle versions are deleted without a murmur.  If it is `nil', the
        !          1024: default, then you are asked whether the excess middle versions should
        !          1025: really be deleted.
        !          1026: 
        !          1027:   Dired's `.' (Period) command can also be used to delete old versions.
        !          1028: *Note Dired::.
        !          1029: 
        !          1030: 
        !          1031: File: emacs  Node: Backup Copying, Prev: Backup Deletion, Up: Backup
        !          1032: 
        !          1033: Copying vs. Renaming
        !          1034: ....................
        !          1035: 
        !          1036:   Backup files can be made by copying the old file or by renaming it.  This
        !          1037: makes a difference when the old file has multiple names.  If the old file
        !          1038: is renamed into the backup file, then the alternate names become names for
        !          1039: the backup file.  If the old file is copied instead, then the alternate
        !          1040: names remain names for the file that you are editing, and the contents
        !          1041: accessed by those names will be the new contents.
        !          1042: 
        !          1043:   The method of making a backup file may also affect the file's owner
        !          1044: and group.  If copying is used, these do not change.  If renaming is used,
        !          1045: you become the file's owner, and the file's group becomes the default
        !          1046: (different operating systems have different defaults for the group).
        !          1047: 
        !          1048:   Having the owner change is usually a good idea, because then the owner
        !          1049: always shows who last edited the file.  Also, the owners of the backups
        !          1050: show who produced those versions.  Occasionally there is a file whose
        !          1051: owner should not change; it is a good idea for such files to contain
        !          1052: local variable lists to set `backup-by-copying-when-mismatch' for
        !          1053: them alone (*Note File Variables::).
        !          1054: 
        !          1055:   The choice of renaming or copying is controlled by three variables.
        !          1056: Normally, renaming is done.  If the variable `backup-by-copying' is
        !          1057: non-`nil', copying is used.  Otherwise, if the variable
        !          1058: `backup-by-copying-when-linked' is non-`nil', then copying is done for
        !          1059: files that have multiple names, but renaming may still done when the file
        !          1060: being edited has only one name.  If the variable
        !          1061: `backup-by-copying-when-mismatch' is non-`nil', then copying is done if
        !          1062: renaming would cause the file's owner or group to change.
        !          1063: 
        !          1064: 
        !          1065: File: emacs  Node: Interlocking, Prev: Backup, Up: Saving
        !          1066: 
        !          1067: Protection against Simultaneous Editing
        !          1068: ---------------------------------------
        !          1069: 
        !          1070:   Simultaneous editing occurs when two users visit the same file, both make
        !          1071: changes, and then both save them.  If nobody were informed that this was
        !          1072: happening, whichever user saved first would later find that his changes
        !          1073: were lost.  On some systems, Emacs notices immediately when the second user
        !          1074: starts to change the file, and issues an immediate warning.  When this is
        !          1075: not possible, or if the second user has gone on to change the file despite
        !          1076: the warning, Emacs checks later when the file is saved, and issues a second
        !          1077: warning when a user is about to overwrite a file containing another user's
        !          1078: changes.  If the editing user takes the proper corrective action at this
        !          1079: point, he can prevent actual loss of work.
        !          1080: 
        !          1081:   When you make the first modification in an Emacs buffer that is visiting
        !          1082: a file, Emacs records that you have locked the file.  (It does this by
        !          1083: writing another file in a directory reserved for this purpose.)  The lock
        !          1084: is removed when you save the changes.  The idea is that the file is locked
        !          1085: whenever the buffer is modified.  If you begin to modify the buffer while
        !          1086: the visited file is locked by someone else, this constitutes a collision,
        !          1087: and Emacs asks you what to do.  It does this by calling the Lisp function
        !          1088: `ask-user-about-lock', which you can redefine for the sake of
        !          1089: customization.  The standard definition of this function asks you a
        !          1090: question and accepts three possible answers:
        !          1091: 
        !          1092: `s'     
        !          1093:      Steal the lock.  Whoever was already changing the file loses the lock,
        !          1094:      and you gain the lock.
        !          1095: `p'     
        !          1096:      Proceed.  Go ahead and edit the file despite its being locked by someone else.
        !          1097: `q'     
        !          1098:      Quit.  This causes an error (`file-locked') and the modification you
        !          1099:      were trying to make in the buffer does not actually take place.
        !          1100: 
        !          1101:   Note that locking works on the basis of a file name; if a file has
        !          1102: multiple names, Emacs does not realize that the two names are the same file
        !          1103: and cannot prevent two user from editing it simultaneously under different
        !          1104: names.  However, basing locking on names means that Emacs can interlock the
        !          1105: editing of new files that will not really exist until they are saved.
        !          1106: 
        !          1107:   Some systems are not configured to allow Emacs to make locks.  On
        !          1108: these systems, Emacs cannot detect trouble in advance, but it still can
        !          1109: detect it in time to prevent you from overwriting someone else's changes.
        !          1110: 
        !          1111:   Every time Emacs saves a buffer, it first checks the last-modification
        !          1112: date of the existing file on disk to see that it has not changed since the
        !          1113: file was last visited or saved.  If the date does not match, it implies
        !          1114: that changes were made in the file in some other way, and these changes are
        !          1115: about to be lost if Emacs actually does save.  To prevent this, Emacs
        !          1116: prints a warning message and asks for confirmation before saving.
        !          1117: Occasionally you will know why the file was changed and know that it does
        !          1118: not matter; then you can answer `yes' and proceed.  Otherwise, you should
        !          1119: cancel the save with `C-g' and investigate the situation.
        !          1120: 
        !          1121:   The first thing you should do when notified that simultaneous editing has
        !          1122: already taken place is to list the directory with `C-u C-x C-d' (*Note
        !          1123: Directory Listing: ListDir.).  This will show the file's current author.
        !          1124: You should attempt to contact him to warn him not to continue editing.
        !          1125: Often the next step is to save the contents of your Emacs buffer under a
        !          1126: different name, and use `diff' to compare the two files.
        !          1127: 
        !          1128:   Simultaneous editing checks are also made when you visit with `C-x
        !          1129: C-f' a file that is already visited and when you start to modify a file.
        !          1130: This is not strictly necessary, but it can cause you to find out about the
        !          1131: problem earlier, when perhaps correction takes less work.
        !          1132: 
        !          1133: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.