info/xemacs.info-6

   1 This is Info file ../info/xemacs.info, produced by Makeinfo version
   2 1.68 from the input file xemacs/xemacs.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * XEmacs: (xemacs).             XEmacs Editor.
   7 END-INFO-DIR-ENTRY
   8
   9    This file documents the XEmacs editor.
  10
  11    Copyright (C) 1985, 1986, 1988 Richard M. Stallman.  Copyright (C)
  12 1991, 1992, 1993, 1994 Lucid, Inc.  Copyright (C) 1993, 1994 Sun
  13 Microsystems, Inc.  Copyright (C) 1995 Amdahl Corporation.
  14
  15    Permission is granted to make and distribute verbatim copies of this
  16 manual provided the copyright notice and this permission notice are
  17 preserved on all copies.
  18
  19    Permission is granted to copy and distribute modified versions of
  20 this manual under the conditions for verbatim copying, provided also
  21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
  22 General Public License" are included exactly as in the original, and
  23 provided that the entire resulting derived work is distributed under the
  24 terms of a permission notice identical to this one.
  25
  26    Permission is granted to copy and distribute translations of this
  27 manual into another language, under the above conditions for modified
  28 versions, except that the sections entitled "The GNU Manifesto",
  29 "Distribution" and "GNU General Public License" may be included in a
  30 translation approved by the author instead of in the original English.
  31
  32 \1f
  33 File: xemacs.info,  Node: Display Vars,  Prev: Selective Display,  Up: Display
  34
  35 Variables Controlling Display
  36 =============================
  37
  38    This section contains information for customization only.  Beginning
  39 users should skip it.
  40
  41    When you reenter XEmacs after suspending, XEmacs normally clears the
  42 screen and redraws the entire display.  On some terminals with more than
  43 one page of memory, it is possible to arrange the termcap entry so that
  44 the `ti' and `te' strings (output to the terminal when XEmacs is
  45 entered and exited, respectively) switch between pages of memory so as
  46 to use one page for XEmacs and another page for other output.  In that
  47 case, you might want to set the variable `no-redraw-on-reenter' to
  48 non-`nil' so that XEmacs will assume, when resumed, that the screen
  49 page it is using still contains what XEmacs last wrote there.
  50
  51    The variable `echo-keystrokes' controls the echoing of
  52 multi-character keys; its value is the number of seconds of pause
  53 required to cause echoing to start, or zero, meaning don't echo at all.
  54 *Note Echo Area::.
  55
  56    If the variable `ctl-arrow' is `nil', control characters in the
  57 buffer are displayed with octal escape sequences, all except newline and
  58 tab.  If its value is `t', then control characters will be printed with
  59 an up-arrow, for example `^A'.
  60
  61    If its value is not `t' and not `nil', then characters whose code is
  62 greater than 160 (that is, the space character (32) with its high bit
  63 set) will be assumed to be printable, and will be displayed without
  64 alteration.  This is the default when running under X Windows, since
  65 XEmacs assumes an ISO/8859-1 character set (also known as "Latin1").
  66 The `ctl-arrow' variable may also be set to an integer, in which case
  67 all characters whose codes are greater than or equal to that value will
  68 be assumed to be printable.
  69
  70    Altering the value of `ctl-arrow' makes it local to the current
  71 buffer; until that time, the default value is in effect.  *Note
  72 Locals::.
  73
  74    Normally, a tab character in the buffer is displayed as whitespace
  75 which extends to the next display tab stop position, and display tab
  76 stops come at intervals equal to eight spaces.  The number of spaces
  77 per tab is controlled by the variable `tab-width', which is made local
  78 by changing it, just like `ctl-arrow'.  Note that how the tab character
  79 in the buffer is displayed has nothing to do with the definition of
  80 <TAB> as a command.
  81
  82    If you set the variable `selective-display-ellipses' to `nil', the
  83 three dots at the end of a line that precedes invisible lines do not
  84 appear.  There is no visible indication of the invisible lines.  This
  85 variable becomes local automatically when set.
  86
  87 \1f
  88 File: xemacs.info,  Node: Search,  Next: Fixit,  Prev: Display,  Up: Top
  89
  90 Searching and Replacement
  91 *************************
  92
  93    Like other editors, Emacs has commands for searching for occurrences
  94 of a string.  The principal search command is unusual in that it is
  95 "incremental": it begins to search before you have finished typing the
  96 search string.  There are also non-incremental search commands more like
  97 those of other editors.
  98
  99    Besides the usual `replace-string' command that finds all
 100 occurrences of one string and replaces them with another, Emacs has a
 101 fancy replacement command called `query-replace' which asks
 102 interactively which occurrences to replace.
 103
 104 * Menu:
 105
 106 * Incremental Search::     Search happens as you type the string.
 107 * Non-Incremental Search:: Specify entire string and then search.
 108 * Word Search::            Search for sequence of words.
 109 * Regexp Search::          Search for match for a regexp.
 110 * Regexps::                Syntax of regular expressions.
 111 * Search Case::            To ignore case while searching, or not.
 112 * Replace::                Search, and replace some or all matches.
 113 * Other Repeating Search:: Operating on all matches for some regexp.
 114
 115 \1f
 116 File: xemacs.info,  Node: Incremental Search,  Next: Non-Incremental Search,  Prev: Search,  Up: Search
 117
 118 Incremental Search
 119 ==================
 120
 121    An incremental search begins searching as soon as you type the first
 122 character of the search string.  As you type in the search string, Emacs
 123 shows you where the string (as you have typed it so far) is found.
 124 When you have typed enough characters to identify the place you want,
 125 you can stop.  Depending on what you do next, you may or may not need to
 126 terminate the search explicitly with a <RET>.
 127
 128 `C-s'
 129      Incremental search forward (`isearch-forward').
 130
 131 `C-r'
 132      Incremental search backward (`isearch-backward').
 133
 134    `C-s' starts an incremental search.  `C-s' reads characters from the
 135 keyboard and positions the cursor at the first occurrence of the
 136 characters that you have typed.  If you type `C-s' and then `F', the
 137 cursor moves right after the first `F'.  Type an `O', and see the
 138 cursor move to after the first `FO'.  After another `O', the cursor is
 139 after the first `FOO' after the place where you started the search.
 140 Meanwhile, the search string `FOO' has been echoed in the echo area.
 141
 142    The echo area display ends with three dots when actual searching is
 143 going on.  When search is waiting for more input, the three dots are
 144 removed.  (On slow terminals, the three dots are not displayed.)
 145
 146    If you make a mistake in typing the search string, you can erase
 147 characters with <DEL>.  Each <DEL> cancels the last character of the
 148 search string.  This does not happen until Emacs is ready to read
 149 another input character; first it must either find, or fail to find,
 150 the character you want to erase.  If you do not want to wait for this
 151 to happen, use `C-g' as described below.
 152
 153    When you are satisfied with the place you have reached, you can type
 154 <RET> (or <C-m>), which stops searching, leaving the cursor where the
 155 search brought it.  Any command not specially meaningful in searches
 156 also stops the search and is then executed.  Thus, typing `C-a' exits
 157 the search and then moves to the beginning of the line.  <RET> is
 158 necessary only if the next command you want to type is a printing
 159 character, <DEL>, <ESC>, or another control character that is special
 160 within searches (`C-q', `C-w', `C-r', `C-s', or `C-y').
 161
 162    Sometimes you search for `FOO' and find it, but were actually
 163 looking for a different occurance of it.  To move to the next occurrence
 164 of the search string, type another `C-s'.  Do this as often as
 165 necessary.  If you overshoot, you can cancel some `C-s' characters with
 166 <DEL>.
 167
 168    After you exit a search, you can search for the same string again by
 169 typing just `C-s C-s': the first `C-s' is the key that invokes
 170 incremental search, and the second `C-s' means "search again".
 171
 172    If the specified string is not found at all, the echo area displays
 173 the text `Failing I-Search'.  The cursor is after the place where Emacs
 174 found as much of your string as it could.  Thus, if you search for
 175 `FOOT', and there is no `FOOT', the cursor may be after the `FOO' in
 176 `FOOL'.  At this point there are several things you can do.  If you
 177 mistyped the search string, correct it.  If you like the place you have
 178 found, you can type <RET> or some other Emacs command to "accept what
 179 the search offered".  Or you can type `C-g', which removes from the
 180 search string the characters that could not be found (the `T' in
 181 `FOOT'), leaving those that were found (the `FOO' in `FOOT').  A second
 182 `C-g' at that point cancels the search entirely, returning point to
 183 where it was when the search started.
 184
 185    If a search is failing and you ask to repeat it by typing another
 186 `C-s', it starts again from the beginning of the buffer.  Repeating a
 187 failing backward search with `C-r' starts again from the end.  This is
 188 called "wrapping around".  `Wrapped' appears in the search prompt once
 189 this has happened.
 190
 191    The `C-g' "quit" character does special things during searches; just
 192 what it does depends on the status of the search.  If the search has
 193 found what you specified and is waiting for input, `C-g' cancels the
 194 entire search.  The cursor moves back to where you started the search.
 195 If `C-g' is typed when there are characters in the search string that
 196 have not been found--because Emacs is still searching for them, or
 197 because it has failed to find them--then the search string characters
 198 which have not been found are discarded from the search string.  The
 199 search is now successful and waiting for more input, so a second `C-g'
 200 cancels the entire search.
 201
 202    To search for a control character such as `C-s' or <DEL> or <ESC>,
 203 you must quote it by typing `C-q' first.  This function of `C-q' is
 204 analogous to its meaning as an Emacs command: it causes the following
 205 character to be treated the way a graphic character would normally be
 206 treated in the same context.
 207
 208    To search backwards, you can use `C-r' instead of `C-s' to start the
 209 search; `C-r' is the key that runs the command (`isearch-backward') to
 210 search backward.  You can also use `C-r' to change from searching
 211 forward to searching backwards.  Do this if a search fails because the
 212 place you started was too far down in the file.  Repeated `C-r' keeps
 213 looking for more occurrences backwards.  `C-s' starts going forward
 214 again.  You can cancel `C-r' in a search with <DEL>.
 215
 216    The characters `C-y' and `C-w' can be used in incremental search to
 217 grab text from the buffer into the search string.  This makes it
 218 convenient to search for another occurrence of text at point.  `C-w'
 219 copies the word after point as part of the search string, advancing
 220 point over that word.  Another `C-s' to repeat the search will then
 221 search for a string including that word.  `C-y' is similar to `C-w' but
 222 copies the rest of the current line into the search string.
 223
 224    The characters `M-p' and `M-n' can be used in an incremental search
 225 to recall things which you have searched for in the past.  A list of
 226 the last 16 things you have searched for is retained, and `M-p' and
 227 `M-n' let you cycle through that ring.
 228
 229    The character `M-<TAB>' does completion on the elements in the
 230 search history ring.  For example, if you know that you have recently
 231 searched for the string `POTATOE', you could type `C-s P O M-<TAB>'.
 232 If you had searched for other strings beginning with `PO' then you
 233 would be shown a list of them, and would need to type more to select
 234 one.
 235
 236    You can change any of the special characters in incremental search
 237 via the normal keybinding mechanism: simply add a binding to the
 238 `isearch-mode-map'.  For example, to make the character `C-b' mean
 239 "search backwards" while in isearch-mode, do this:
 240
 241      (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
 242
 243    These are the default bindings of isearch-mode:
 244
 245 `DEL'
 246      Delete a character from the incremental search string
 247      (`isearch-delete-char').
 248
 249 `RET'
 250      Exit incremental search (`isearch-exit').
 251
 252 `C-q'
 253      Quote special characters for incremental search
 254      (`isearch-quote-char').
 255
 256 `C-s'
 257      Repeat incremental search forward (`isearch-repeat-forward').
 258
 259 `C-r'
 260      Repeat incremental search backward (`isearch-repeat-backward').
 261
 262 `C-y'
 263      Pull rest of line from buffer into search string
 264      (`isearch-yank-line').
 265
 266 `C-w'
 267      Pull next word from buffer into search string
 268      (`isearch-yank-word').
 269
 270 `C-g'
 271      Cancels input back to what has been found successfully, or aborts
 272      the isearch (`isearch-abort').
 273
 274 `M-p'
 275      Recall the previous element in the isearch history ring
 276      (`isearch-ring-retreat').
 277
 278 `M-n'
 279      Recall the next element in the isearch history ring
 280      (`isearch-ring-advance').
 281
 282 `M-<TAB>'
 283      Do completion on the elements in the isearch history ring
 284      (`isearch-complete').
 285
 286    Any other character which is normally inserted into a buffer when
 287 typed is automatically added to the search string in isearch-mode.
 288
 289 Slow Terminal Incremental Search
 290 --------------------------------
 291
 292    Incremental search on a slow terminal uses a modified style of
 293 display that is designed to take less time.  Instead of redisplaying
 294 the buffer at each place the search gets to, it creates a new
 295 single-line window and uses that to display the line the search has
 296 found.  The single-line window appears as soon as point gets outside of
 297 the text that is already on the screen.
 298
 299    When the search is terminated, the single-line window is removed.
 300 Only at this time the window in which the search was done is
 301 redisplayed to show its new value of point.
 302
 303    The three dots at the end of the search string, normally used to
 304 indicate that searching is going on, are not displayed in slow style
 305 display.
 306
 307    The slow terminal style of display is used when the terminal baud
 308 rate is less than or equal to the value of the variable
 309 `search-slow-speed', initially 1200.
 310
 311    The number of lines to use in slow terminal search display is
 312 controlled by the variable `search-slow-window-lines'.  Its normal
 313 value is 1.
 314
 315 \1f
 316 File: xemacs.info,  Node: Non-Incremental Search,  Next: Word Search,  Prev: Incremental Search,  Up: Search
 317
 318 Non-Incremental Search
 319 ======================
 320
 321    Emacs also has conventional non-incremental search commands, which
 322 require you type the entire search string before searching begins.
 323
 324 `C-s <RET> STRING <RET>'
 325      Search for STRING.
 326
 327 `C-r <RET> STRING <RET>'
 328      Search backward for STRING.
 329
 330    To do a non-incremental search, first type `C-s <RET>' (or `C-s
 331 C-m').  This enters the minibuffer to read the search string.
 332 Terminate the string with <RET> to start the search.  If the string is
 333 not found, the search command gets an error.
 334
 335    By default, `C-s' invokes incremental search, but if you give it an
 336 empty argument, which would otherwise be useless, it invokes
 337 non-incremental search.  Therefore, `C-s <RET>' invokes non-incremental
 338 search.  `C-r <RET>' also works this way.
 339
 340    Forward and backward non-incremental searches are implemented by the
 341 commands `search-forward' and `search-backward'.  You can bind these
 342 commands to keys.  The reason that incremental search is programmed to
 343 invoke them as well is that `C-s <RET>' is the traditional sequence of
 344 characters used in Emacs to invoke non-incremental search.
 345
 346    Non-incremental searches performed using `C-s <RET>' do not call
 347 `search-forward' right away.  They first check if the next character is
 348 `C-w', which requests a word search.  *Note Word Search::.
 349
 350 \1f
 351 File: xemacs.info,  Node: Word Search,  Next: Regexp Search,  Prev: Non-Incremental Search,  Up: Search
 352
 353 Word Search
 354 ===========
 355
 356    Word search looks for a sequence of words without regard to how the
 357 words are separated.  More precisely, you type a string of many words,
 358 using single spaces to separate them, and the string is found even if
 359 there are multiple spaces, newlines or other punctuation between the
 360 words.
 361
 362    Word search is useful in editing documents formatted by text
 363 formatters.  If you edit while looking at the printed, formatted
 364 version, you can't tell where the line breaks are in the source file.
 365 Word search, allows you to search  without having to know the line
 366 breaks.
 367
 368 `C-s <RET> C-w WORDS <RET>'
 369      Search for WORDS, ignoring differences in punctuation.
 370
 371 `C-r <RET> C-w WORDS <RET>'
 372      Search backward for WORDS, ignoring differences in punctuation.
 373
 374    Word search is a special case of non-incremental search.  It is
 375 invoked with `C-s <RET> C-w' followed by the search string, which must
 376 always be terminated with another <RET>.  Being non-incremental, this
 377 search does not start until the argument is terminated.  It works by
 378 constructing a regular expression and searching for that.  *Note Regexp
 379 Search::.
 380
 381    You can do a backward word search with `C-r <RET> C-w'.
 382
 383    Forward and backward word searches are implemented by the commands
 384 `word-search-forward' and `word-search-backward'.  You can bind these
 385 commands to keys.  The reason that incremental search is programmed to
 386 invoke them as well is that `C-s <RET> C-w' is the traditional Emacs
 387 sequence of keys for word search.
 388
 389 \1f
 390 File: xemacs.info,  Node: Regexp Search,  Next: Regexps,  Prev: Word Search,  Up: Search
 391
 392 Regular Expression Search
 393 =========================
 394
 395    A "regular expression" ("regexp", for short) is a pattern that
 396 denotes a set of strings, possibly an infinite set.  Searching for
 397 matches for a regexp is a powerful operation that editors on Unix
 398 systems have traditionally offered.  In XEmacs, you can search for the
 399 next match for a regexp either incrementally or not.
 400
 401    Incremental search for a regexp is done by typing `M-C-s'
 402 (`isearch-forward-regexp').  This command reads a search string
 403 incrementally just like `C-s', but it treats the search string as a
 404 regexp rather than looking for an exact match against the text in the
 405 buffer.  Each time you add text to the search string, you make the
 406 regexp longer, and the new regexp is searched for.  A reverse regexp
 407 search command `isearch-backward-regexp' also exists, but no key runs
 408 it.
 409
 410    All of the control characters that do special things within an
 411 ordinary incremental search have the same functionality in incremental
 412 regexp search.  Typing `C-s' or `C-r' immediately after starting a
 413 search retrieves the last incremental search regexp used: incremental
 414 regexp and non-regexp searches have independent defaults.
 415
 416    Non-incremental search for a regexp is done by the functions
 417 `re-search-forward' and `re-search-backward'.  You can invoke them with
 418 `M-x' or bind them to keys.  You can also call `re-search-forward' by
 419 way of incremental regexp search with `M-C-s <RET>'.
 420
 421 \1f
 422 File: xemacs.info,  Node: Regexps,  Next: Search Case,  Prev: Regexp Search,  Up: Search
 423
 424 Syntax of Regular Expressions
 425 =============================
 426
 427    Regular expressions have a syntax in which a few characters are
 428 special constructs and the rest are "ordinary".  An ordinary character
 429 is a simple regular expression which matches that character and nothing
 430 else.  The special characters are `$', `^', `.', `*', `+', `?', `[',
 431 `]' and `\'; no new special characters will be defined.  Any other
 432 character appearing in a regular expression is ordinary, unless a `\'
 433 precedes it.
 434
 435    For example, `f' is not a special character, so it is ordinary, and
 436 therefore `f' is a regular expression that matches the string `f' and
 437 no other string.  (It does not match the string `ff'.)  Likewise, `o'
 438 is a regular expression that matches only `o'.
 439
 440    Any two regular expressions A and B can be concatenated.  The result
 441 is a regular expression which matches a string if A matches some amount
 442 of the beginning of that string and B matches the rest of the string.
 443
 444    As a simple example, you can concatenate the regular expressions `f'
 445 and `o' to get the regular expression `fo', which matches only the
 446 string `fo'.  To do something nontrivial, you need to use one of the
 447 following special characters:
 448
 449 `. (Period)'
 450      is a special character that matches any single character except a
 451      newline.  Using concatenation, you can make regular expressions
 452      like `a.b', which matches any three-character string which begins
 453      with `a' and ends with `b'.
 454
 455 `*'
 456      is not a construct by itself; it is a suffix, which means the
 457      preceding regular expression is to be repeated as many times as
 458      possible.  In `fo*', the `*' applies to the `o', so `fo*' matches
 459      one `f' followed by any number of `o's.  The case of zero `o's is
 460      allowed: `fo*' does match `f'.
 461
 462      `*' always applies to the smallest possible preceding expression.
 463      Thus, `fo*' has a repeating `o', not a repeating `fo'.
 464
 465      The matcher processes a `*' construct by immediately matching as
 466      many repetitions as it can find.  Then it continues with the rest
 467      of the pattern.  If that fails, backtracking occurs, discarding
 468      some of the matches of the `*'-modified construct in case that
 469      makes it possible to match the rest of the pattern.  For example,
 470      matching `ca*ar' against the string `caaar', the `a*' first tries
 471      to match all three `a's; but the rest of the pattern is `ar' and
 472      there is only `r' left to match, so this try fails.  The next
 473      alternative is for `a*' to match only two `a's.  With this choice,
 474      the rest of the regexp matches successfully.
 475
 476 `+'
 477      is a suffix character similar to `*' except that it requires that
 478      the preceding expression be matched at least once.  For example,
 479      `ca+r' will match the strings `car' and `caaaar' but not the
 480      string `cr', whereas `ca*r' would match all three strings.
 481
 482 `?'
 483      is a suffix character similar to `*' except that it can match the
 484      preceding expression either once or not at all.  For example,
 485      `ca?r' will match `car' or `cr'; nothing else.
 486
 487 `[ ... ]'
 488      `[' begins a "character set", which is terminated by a `]'.  In
 489      the simplest case, the characters between the two form the set.
 490      Thus, `[ad]' matches either one `a' or one `d', and `[ad]*'
 491      matches any string composed of just `a's and `d's (including the
 492      empty string), from which it follows that `c[ad]*r' matches `cr',
 493      `car', `cdr', `caddaar', etc.
 494
 495      You can include character ranges in a character set by writing two
 496      characters with a `-' between them.  Thus, `[a-z]' matches any
 497      lower-case letter.  Ranges may be intermixed freely with individual
 498      characters, as in `[a-z$%.]', which matches any lower-case letter
 499      or `$', `%', or period.
 500
 501      Note that inside a character set the usual special characters are
 502      not special any more.  A completely different set of special
 503      characters exists inside character sets: `]', `-', and `^'.
 504
 505      To include a `]' in a character set, you must make it the first
 506      character.  For example, `[]a]' matches `]' or `a'.  To include a
 507      `-', write `---', which is a range containing only `-'.  To
 508      include `^', make it other than the first character in the set.
 509
 510 `[^ ... ]'
 511      `[^' begins a "complement character set", which matches any
 512      character except the ones specified.  Thus, `[^a-z0-9A-Z]' matches
 513      all characters except letters and digits.
 514
 515      `^' is not special in a character set unless it is the first
 516      character.  The character following the `^' is treated as if it
 517      were first (`-' and `]' are not special there).
 518
 519      Note that a complement character set can match a newline, unless
 520      newline is mentioned as one of the characters not to match.
 521
 522 `^'
 523      is a special character that matches the empty string, but only if
 524      at the beginning of a line in the text being matched.  Otherwise,
 525      it fails to match anything.  Thus, `^foo' matches a `foo' that
 526      occurs at the beginning of a line.
 527
 528 `$'
 529      is similar to `^' but matches only at the end of a line.  Thus,
 530      `xx*$' matches a string of one `x' or more at the end of a line.
 531
 532 `\'
 533      does two things: it quotes the special characters (including `\'),
 534      and it introduces additional special constructs.
 535
 536      Because `\' quotes special characters, `\$' is a regular
 537      expression that matches only `$', and `\[' is a regular expression
 538      that matches only `[', and so on.
 539
 540    Note: for historical compatibility, special characters are treated as
 541 ordinary ones if they are in contexts where their special meanings make
 542 no sense.  For example, `*foo' treats `*' as ordinary since there is no
 543 preceding expression on which the `*' can act.  It is poor practice to
 544 depend on this behavior; better to quote the special character anyway,
 545 regardless of where is appears.
 546
 547    Usually, `\' followed by any character matches only that character.
 548 However, there are several exceptions: characters which, when preceded
 549 by `\', are special constructs.  Such characters are always ordinary
 550 when encountered on their own.  Here is a table of `\' constructs.
 551
 552 `\|'
 553      specifies an alternative.  Two regular expressions A and B with
 554      `\|' in between form an expression that matches anything A or B
 555      matches.
 556
 557      Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
 558
 559      `\|' applies to the largest possible surrounding expressions.
 560      Only a surrounding `\( ... \)' grouping can limit the grouping
 561      power of `\|'.
 562
 563      Full backtracking capability exists to handle multiple uses of
 564      `\|'.
 565
 566 `\( ... \)'
 567      is a grouping construct that serves three purposes:
 568
 569        1. To enclose a set of `\|' alternatives for other operations.
 570           Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
 571
 572        2. To enclose a complicated expression for the postfix `*' to
 573           operate on.  Thus, `ba\(na\)*' matches `bananana', etc., with
 574           any (zero or more) number of `na' strings.
 575
 576        3. To mark a matched substring for future reference.
 577
 578
 579      This last application is not a consequence of the idea of a
 580      parenthetical grouping; it is a separate feature which happens to
 581      be assigned as a second meaning to the same `\( ... \)' construct
 582      because in practice there is no conflict between the two meanings.
 583      Here is an explanation:
 584
 585 `\DIGIT'
 586      after the end of a `\( ... \)' construct, the matcher remembers the
 587      beginning and end of the text matched by that construct.  Then,
 588      later on in the regular expression, you can use `\' followed by
 589      DIGIT to mean "match the same text matched the DIGIT'th time by the
 590      `\( ... \)' construct."
 591
 592      The strings matching the first nine `\( ... \)' constructs
 593      appearing in a regular expression are assigned numbers 1 through 9
 594      in order that the open-parentheses appear in the regular
 595      expression.  `\1' through `\9' may be used to refer to the text
 596      matched by the corresponding `\( ... \)' construct.
 597
 598      For example, `\(.*\)\1' matches any newline-free string that is
 599      composed of two identical halves.  The `\(.*\)' matches the first
 600      half, which may be anything, but the `\1' that follows must match
 601      the same exact text.
 602
 603 `\`'
 604      matches the empty string, provided it is at the beginning of the
 605      buffer.
 606
 607 `\''
 608      matches the empty string, provided it is at the end of the buffer.
 609
 610 `\b'
 611      matches the empty string, provided it is at the beginning or end
 612      of a word.  Thus, `\bfoo\b' matches any occurrence of `foo' as a
 613      separate word.  `\bballs?\b' matches `ball' or `balls' as a
 614      separate word.
 615
 616 `\B'
 617      matches the empty string, provided it is not at the beginning or
 618      end of a word.
 619
 620 `\<'
 621      matches the empty string, provided it is at the beginning of a
 622      word.
 623
 624 `\>'
 625      matches the empty string, provided it is at the end of a word.
 626
 627 `\w'
 628      matches any word-constituent character.  The editor syntax table
 629      determines which characters these are.
 630
 631 `\W'
 632      matches any character that is not a word-constituent.
 633
 634 `\sCODE'
 635      matches any character whose syntax is CODE.  CODE is a character
 636      which represents a syntax code: thus, `w' for word constituent,
 637      `-' for whitespace, `(' for open-parenthesis, etc.  *Note Syntax::.
 638
 639 `\SCODE'
 640      matches any character whose syntax is not CODE.
 641
 642    Here is a complicated regexp used by Emacs to recognize the end of a
 643 sentence together with any whitespace that follows.  It is given in Lisp
 644 syntax to enable you to distinguish the spaces from the tab characters.
 645 In Lisp syntax, the string constant begins and ends with a
 646 double-quote.  `\"' stands for a double-quote as part of the regexp,
 647 `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
 648 a newline.
 649
 650      "[.?!][]\"')]*\\($\\|\t\\|  \\)[ \t\n]*"
 651
 652 This regexp contains four parts: a character set matching period, `?'
 653 or `!'; a character set matching close-brackets, quotes or parentheses,
 654 repeated any number of times; an alternative in backslash-parentheses
 655 that matches end-of-line, a tab or two spaces; and a character set
 656 matching whitespace characters, repeated any number of times.
 657
 658 \1f
 659 File: xemacs.info,  Node: Search Case,  Next: Replace,  Prev: Regexps,  Up: Search
 660
 661 Searching and Case
 662 ==================
 663
 664    All searches in Emacs normally ignore the case of the text they are
 665 searching through; if you specify searching for `FOO', `Foo' and `foo'
 666 are also considered a match.  Regexps, and in particular character
 667 sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
 668
 669    If you want a case-sensitive search, set the variable
 670 `case-fold-search' to `nil'.  Then all letters must match exactly,
 671 including case. `case-fold-search' is a per-buffer variable; altering
 672 it affects only the current buffer, but there is a default value which
 673 you can change as well.  *Note Locals::.  You can also use Case
 674 Sensitive Search from the Options menu on your screen.
 675
 676 \1f
 677 File: xemacs.info,  Node: Replace,  Next: Other Repeating Search,  Prev: Search Case,  Up: Search
 678
 679 Replacement Commands
 680 ====================
 681
 682    Global search-and-replace operations are not needed as often in
 683 Emacs as they are in other editors, but they are available.  In
 684 addition to the simple `replace-string' command which is like that
 685 found in most editors, there is a `query-replace' command which asks
 686 you, for each occurrence of a pattern, whether to replace it.
 687
 688    The replace commands all replace one string (or regexp) with one
 689 replacement string.  It is possible to perform several replacements in
 690 parallel using the command `expand-region-abbrevs'.  *Note Expanding
 691 Abbrevs::.
 692
 693 * Menu:
 694
 695 * Unconditional Replace::  Replacing all matches for a string.
 696 * Regexp Replace::         Replacing all matches for a regexp.
 697 * Replacement and Case::   How replacements preserve case of letters.
 698 * Query Replace::          How to use querying.
 699
 700 \1f
 701 File: xemacs.info,  Node: Unconditional Replace,  Next: Regexp Replace,  Prev: Replace,  Up: Replace
 702
 703 Unconditional Replacement
 704 -------------------------
 705
 706 `M-x replace-string <RET> STRING <RET> NEWSTRING <RET>'
 707      Replace every occurrence of STRING with NEWSTRING.
 708
 709 `M-x replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
 710      Replace every match for REGEXP with NEWSTRING.
 711
 712    To replace every instance of `foo' after point with `bar', use the
 713 command `M-x replace-string' with the two arguments `foo' and `bar'.
 714 Replacement occurs only after point: if you want to cover the whole
 715 buffer you must go to the beginning first.  By default, all occurrences
 716 up to the end of the buffer are replaced.  To limit replacement to part
 717 of the buffer, narrow to that part of the buffer before doing the
 718 replacement (*note Narrowing::.).
 719
 720    When `replace-string' exits, point is left at the last occurrence
 721 replaced.  The value of point when the `replace-string' command was
 722 issued is remembered on the mark ring; `C-u C-<SPC>' moves back there.
 723
 724    A numeric argument restricts replacement to matches that are
 725 surrounded by word boundaries.
 726
 727 \1f
 728 File: xemacs.info,  Node: Regexp Replace,  Next: Replacement and Case,  Prev: Unconditional Replace,  Up: Replace
 729
 730 Regexp Replacement
 731 ------------------
 732
 733    `replace-string' replaces exact matches for a single string.  The
 734 similar command `replace-regexp' replaces any match for a specified
 735 pattern.
 736
 737    In `replace-regexp', the NEWSTRING need not be constant.  It can
 738 refer to all or part of what is matched by the REGEXP.  `\&' in
 739 NEWSTRING stands for the entire text being replaced.  `\D' in
 740 NEWSTRING, where D is a digit, stands for whatever matched the D'th
 741 parenthesized grouping in REGEXP.  For example,
 742
 743      M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>
 744
 745 would replace (for example) `cadr' with `cadr-safe' and `cddr' with
 746 `cddr-safe'.
 747
 748      M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>
 749
 750 would perform exactly the opposite replacements.  To include a `\' in
 751 the text to replace with, you must give `\\'.
 752
 753 \1f
 754 File: xemacs.info,  Node: Replacement and Case,  Next: Query Replace,  Prev: Regexp Replace,  Up: Replace
 755
 756 Replace Commands and Case
 757 -------------------------
 758
 759    If the arguments to a replace command are in lower case, the command
 760 preserves case when it makes a replacement.  Thus, the following
 761 command:
 762
 763      M-x replace-string <RET> foo <RET> bar <RET>
 764
 765 replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
 766 and `Foo' with `Bar'.  If upper-case letters are used in the second
 767 argument, they remain upper-case every time that argument is inserted.
 768 If upper-case letters are used in the first argument, the second
 769 argument is always substituted exactly as given, with no case
 770 conversion.  Likewise, if the variable `case-replace' is set to `nil',
 771 replacement is done without case conversion.  If `case-fold-search' is
 772 set to `nil', case is significant in matching occurrences of `foo' to
 773 replace; also, case conversion of the replacement string is not done.
 774
 775 \1f
 776 File: xemacs.info,  Node: Query Replace,  Prev: Replacement and Case,  Up: Replace
 777
 778 Query Replace
 779 -------------
 780
 781 `M-% STRING <RET> NEWSTRING <RET>'
 782 `M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
 783      Replace some occurrences of STRING with NEWSTRING.
 784
 785 `M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
 786      Replace some matches for REGEXP with NEWSTRING.
 787
 788    If you want to change only some of the occurrences of `foo' to
 789 `bar', not all of them, you can use `query-replace' instead of `M-%'.
 790 This command finds occurrences of `foo' one by one, displays each
 791 occurrence, and asks you whether to replace it.  A numeric argument to
 792 `query-replace' tells it to consider only occurrences that are bounded
 793 by word-delimiter characters.
 794
 795    Aside from querying, `query-replace' works just like
 796 `replace-string', and `query-replace-regexp' works just like
 797 `replace-regexp'.
 798
 799    The things you can type when you are shown an occurrence of STRING
 800 or a match for REGEXP are:
 801
 802 `<SPC>'
 803      to replace the occurrence with NEWSTRING.  This preserves case,
 804      just like `replace-string', provided `case-replace' is non-`nil',
 805      as it normally is.
 806
 807 `<DEL>'
 808      to skip to the next occurrence without replacing this one.
 809
 810 `, (Comma)'
 811      to replace this occurrence and display the result.  You are then
 812      prompted for another input character.  However, since the
 813      replacement has already been made, <DEL> and <SPC> are equivalent.
 814      At this point, you can type `C-r' (see below) to alter the
 815      replaced text.  To undo the replacement, you can type `C-x u'.
 816      This exits the `query-replace'.  If you want to do further
 817      replacement you must use `C-x ESC' to restart (*note
 818      Repetition::.).
 819
 820 `<ESC>'
 821      to exit without doing any more replacements.
 822
 823 `. (Period)'
 824      to replace this occurrence and then exit.
 825
 826 `!'
 827      to replace all remaining occurrences without asking again.
 828
 829 `^'
 830      to go back to the location of the previous occurrence (or what
 831      used to be an occurrence), in case you changed it by mistake.
 832      This works by popping the mark ring.  Only one `^' in a row is
 833      allowed, because only one previous replacement location is kept
 834      during `query-replace'.
 835
 836 `C-r'
 837      to enter a recursive editing level, in case the occurrence needs
 838      to be edited rather than just replaced with NEWSTRING.  When you
 839      are done, exit the recursive editing level with `C-M-c' and the
 840      next occurrence will be displayed.  *Note Recursive Edit::.
 841
 842 `C-w'
 843      to delete the occurrence, and then enter a recursive editing level
 844      as in `C-r'.  Use the recursive edit to insert text to replace the
 845      deleted occurrence of STRING.  When done, exit the recursive
 846      editing level with `C-M-c' and the next occurrence will be
 847      displayed.
 848
 849 `C-l'
 850      to redisplay the screen and then give another answer.
 851
 852 `C-h'
 853      to display a message summarizing these options, then give another
 854      answer.
 855
 856    If you type any other character, Emacs exits the `query-replace', and
 857 executes the character as a command.  To restart the `query-replace',
 858 use `C-x <ESC>', which repeats the `query-replace' because it used the
 859 minibuffer to read its arguments.  *Note C-x ESC: Repetition.
 860
 861 \1f
 862 File: xemacs.info,  Node: Other Repeating Search,  Prev: Replace,  Up: Search
 863
 864 Other Search-and-Loop Commands
 865 ==============================
 866
 867    Here are some other commands that find matches for a regular
 868 expression.  They all operate from point to the end of the buffer.
 869
 870 `M-x occur'
 871      Print each line that follows point and contains a match for the
 872      specified regexp.  A numeric argument specifies the number of
 873      context lines to print before and after each matching line; the
 874      default is none.
 875
 876      The buffer `*Occur*' containing the output serves as a menu for
 877      finding occurrences in their original context.  Find an occurrence
 878      as listed in `*Occur*', position point there, and type `C-c C-c';
 879      this switches to the buffer that was searched and moves point to
 880      the original of the same occurrence.
 881
 882 `M-x list-matching-lines'
 883      Synonym for `M-x occur'.
 884
 885 `M-x count-matches'
 886      Print the number of matches following point for the specified
 887      regexp.
 888
 889 `M-x delete-non-matching-lines'
 890      Delete each line that follows point and does not contain a match
 891      for the specified regexp.
 892
 893 `M-x delete-matching-lines'
 894      Delete each line that follows point and contains a match for the
 895      specified regexp.
 896
 897 \1f
 898 File: xemacs.info,  Node: Fixit,  Next: Files,  Prev: Search,  Up: Top
 899
 900 Commands for Fixing Typos
 901 *************************
 902
 903    This chapter describes commands that are especially useful when you
 904 catch a mistake in your text just after you have made it, or when you
 905 change your mind while composing text on line.
 906
 907 * Menu:
 908
 909 * Kill Errors:: Commands to kill a batch of recently entered text.
 910 * Transpose::   Exchanging two characters, words, lines, lists...
 911 * Fixing Case:: Correcting case of last word entered.
 912 * Spelling::    Apply spelling checker to a word, or a whole file.
 913
 914 \1f
 915 File: xemacs.info,  Node: Kill Errors,  Next: Transpose,  Prev: Fixit,  Up: Fixit
 916
 917 Killing Your Mistakes
 918 =====================
 919
 920 `<DEL>'
 921      Delete last character (`delete-backward-char').
 922
 923 `M-<DEL>'
 924      Kill last word (`backward-kill-word').
 925
 926 `C-x <DEL>'
 927      Kill to beginning of sentence (`backward-kill-sentence').
 928
 929    The <DEL> character (`delete-backward-char') is the most important
 930 correction command.  When used among graphic (self-inserting)
 931 characters, it can be thought of as canceling the last character typed.
 932
 933    When your mistake is longer than a couple of characters, it might be
 934 more convenient to use `M-<DEL>' or `C-x <DEL>'.  `M-<DEL>' kills back
 935 to the start of the last word, and `C-x <DEL>' kills back to the start
 936 of the last sentence.  `C-x <DEL>' is particularly useful when you are
 937 thinking of what to write as you type it, in case you change your mind
 938 about phrasing.  `M-<DEL>' and `C-x <DEL>' save the killed text for
 939 `C-y' and `M-y' to retrieve.  *Note Yanking::.
 940
 941    `M-<DEL>' is often useful even when you have typed only a few
 942 characters wrong, if you know you are confused in your typing and aren't
 943 sure exactly what you typed.  At such a time, you cannot correct with
 944 <DEL> except by looking at the screen to see what you did.  It requires
 945 less thought to kill the whole word and start over.
 946
 947 \1f
 948 File: xemacs.info,  Node: Transpose,  Next: Fixing Case,  Prev: Kill Errors,  Up: Fixit
 949
 950 Transposing Text
 951 ================
 952
 953 `C-t'
 954      Transpose two characters (`transpose-chars').
 955
 956 `M-t'
 957      Transpose two words (`transpose-words').
 958
 959 `C-M-t'
 960      Transpose two balanced expressions (`transpose-sexps').
 961
 962 `C-x C-t'
 963      Transpose two lines (`transpose-lines').
 964
 965    The common error of transposing two adjacent characters can be fixed
 966 with the `C-t' command (`transpose-chars').  Normally, `C-t' transposes
 967 the two characters on either side of point.  When given at the end of a
 968 line, `C-t' transposes the last two characters on the line, rather than
 969 transposing the last character of the line with the newline, which
 970 would be useless.  If you catch a transposition error right away, you
 971 can fix it with just `C-t'.  If you catch the error later,  move the
 972 cursor back to between the two transposed characters.  If you
 973 transposed a space with the last character of the word before it, the
 974 word motion commands are a good way of getting there.  Otherwise, a
 975 reverse search (`C-r') is often the best way.  *Note Search::.
 976
 977    `Meta-t' (`transpose-words') transposes the word before point with
 978 the word after point.  It moves point forward over a word, dragging the
 979 word preceding or containing point forward as well.  The punctuation
 980 characters between the words do not move.  For example, `FOO, BAR'
 981 transposes into `BAR, FOO' rather than `BAR FOO,'.
 982
 983    `C-M-t' (`transpose-sexps') is a similar command for transposing two
 984 expressions (*note Lists::.), and `C-x C-t' (`transpose-lines')
 985 exchanges lines.  It works like `M-t' but in determines the division of
 986 the text into syntactic units differently.
 987
 988    A numeric argument to a transpose command serves as a repeat count:
 989 it tells the transpose command to move the character (word, sexp, line)
 990 before or containing point across several other characters (words,
 991 sexps, lines).  For example, `C-u 3 C-t' moves the character before
 992 point forward across three other characters.  This is equivalent to
 993 repeating `C-t' three times.  `C-u - 4 M-t' moves the word before point
 994 backward across four words.  `C-u - C-M-t' would cancel the effect of
 995 plain `C-M-t'.
 996
 997    A numeric argument of zero transposes the character (word, sexp,
 998 line) ending after point with the one ending after the mark (otherwise a
 999 command with a repeat count of zero would do nothing).
1000
1001 \1f
1002 File: xemacs.info,  Node: Fixing Case,  Next: Spelling,  Prev: Transpose,  Up: Fixit
1003
1004 Case Conversion
1005 ===============
1006
1007 `M-- M-l'
1008      Convert last word to lower case.  Note that `Meta--' is
1009      "Meta-minus."
1010
1011 `M-- M-u'
1012      Convert last word to all upper case.
1013
1014 `M-- M-c'
1015      Convert last word to lower case with capital initial.
1016
1017    A  common error is to type words in the wrong case.  Because of this,
1018 the word case-conversion commands `M-l', `M-u', and `M-c' do not move
1019 the cursor when used with a negative argument.  As soon as you see you
1020 have mistyped the last word, you can simply case-convert it and
1021 continue typing.  *Note Case::.
1022
1023 \1f
1024 File: xemacs.info,  Node: Spelling,  Prev: Fixing Case,  Up: Fixit
1025
1026 Checking and Correcting Spelling
1027 ================================
1028
1029 `M-$'
1030      Check and correct spelling of word (`spell-word').
1031
1032 `M-x spell-buffer'
1033      Check and correct spelling of each word in the buffer.
1034
1035 `M-x spell-region'
1036      Check and correct spelling of each word in the region.
1037
1038 `M-x spell-string'
1039      Check spelling of specified word.
1040
1041    To check the spelling of the word before point, and optionally
1042 correct it, use the command `M-$' (`spell-word').  This command runs an
1043 inferior process containing the `spell' program to see whether the word
1044 is correct English.  If it is not, it asks you to edit the word (in the
1045 minibuffer) into a corrected spelling, and then performs a
1046 `query-replace' to substitute the corrected spelling for the old one
1047 throughout the buffer.
1048
1049    If you exit the minibuffer without altering the original spelling, it
1050 means you do not want to do anything to that word.  In that case, the
1051 `query-replace' is not done.
1052
1053    `M-x spell-buffer' checks each word in the buffer the same way that
1054 `spell-word' does, doing a `query-replace' for every incorrect word if
1055 appropriate.
1056
1057    `M-x spell-region' is similar to `spell-buffer' but operates only on
1058 the region, not the entire buffer.
1059
1060    `M-x spell-string' reads a string as an argument and checks whether
1061 that is a correctly spelled English word.  It prints a message giving
1062 the answer in the echo area.
1063
1064 \1f
1065 File: xemacs.info,  Node: Files,  Next: Buffers,  Prev: Fixit,  Up: Top
1066
1067 File Handling
1068 *************
1069
1070    The basic unit of stored data in Unix is the "file".  To edit a file,
1071 you must tell Emacs to examine the file and prepare a buffer containing
1072 a copy of the file's text.  This is called "visiting" the file.  Editing
1073 commands apply directly to text in the buffer; that is, to the copy
1074 inside Emacs.  Your changes appear in the file itself only when you
1075 "save" the buffer back into the file.
1076
1077    In addition to visiting and saving files, Emacs can delete, copy,
1078 rename, and append to files, and operate on file directories.
1079
1080 * Menu:
1081
1082 * File Names::       How to type and edit file name arguments.
1083 * Visiting::         Visiting a file prepares Emacs to edit the file.
1084 * Saving::           Saving makes your changes permanent.
1085 * Reverting::        Reverting cancels all the changes not saved.
1086 * Auto Save::        Auto Save periodically protects against loss of data.
1087 * Version Control::  Version control systems (RCS and SCCS).
1088 * ListDir::          Listing the contents of a file directory.
1089 * Comparing Files::  Finding where two files differ.
1090 * Dired::            "Editing" a directory to delete, rename, etc.
1091                      the files in it.
1092 * Misc File Ops::    Other things you can do on files.
1093
1094 \1f
1095 File: xemacs.info,  Node: File Names,  Next: Visiting,  Prev: Files,  Up: Files
1096
1097 File Names
1098 ==========
1099
1100    Most Emacs commands that operate on a file require you to specify the
1101 file name.  (Saving and reverting are exceptions; the buffer knows which
1102 file name to use for them.)  File names are specified in the minibuffer
1103 (*note Minibuffer::.).  "Completion" is available, to make it easier to
1104 specify long file names.  *Note Completion::.
1105
1106    There is always a "default file name" which is used if you enter an
1107 empty argument by typing just <RET>.  Normally the default file name is
1108 the name of the file visited in the current buffer; this makes it easy
1109 to operate on that file with any of the Emacs file commands.
1110
1111    Each buffer has a default directory, normally the same as the
1112 directory of the file visited in that buffer.  When Emacs reads a file
1113 name, the default directory is used if you do not specify a directory.
1114 If you specify a directory in a relative fashion, with a name that does
1115 not start with a slash, it is interpreted with respect to the default
1116 directory.  The default directory of the current buffer is kept in the
1117 variable `default-directory', which has a separate value in every
1118 buffer.  The value of the variable should end with a slash.
1119
1120    For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
1121 the default directory is `/u/rms/gnu/'.  If you type just `foo', which
1122 does not specify a directory, it is short for `/u/rms/gnu/foo'.
1123 `../.login' would stand for `/u/rms/.login'.  `new/foo' would stand for
1124 the filename `/u/rms/gnu/new/foo'.
1125
1126    The variable `default-directory-alist' takes an alist of major modes
1127 and their opinions on `default-directory' as a Lisp expression to
1128 evaluate.  A resulting value of `nil' is ignored in favor of
1129 `default-directory'.
1130
1131    You can create a new directory with the function `make-directory',
1132 which takes as an argument a file name string. The current directory is
1133 displayed in the minibuffer when the function is called; you can delete
1134 the old directory name and supply a new directory name. For example, if
1135 the current directory is `/u/rms/gnu', you can delete `gnu' and type
1136 `oryx' and <RET> to create `/u/rms/oryx'.  Removing a directory is
1137 similar to creating one.  To remove a directory, use
1138 `remove-directory'; it takes one argument, a file name string.
1139
1140    The command `M-x pwd' prints the current buffer's default directory,
1141 and the command `M-x cd' sets it (to a value read using the
1142 minibuffer).  A buffer's default directory changes only when the `cd'
1143 command is used.  A file-visiting buffer's default directory is
1144 initialized to the directory of the file that is visited there.  If a
1145 buffer is created with `C-x b', its default directory is copied from
1146 that of the buffer that was current at the time.
1147
1148    The default directory name actually appears in the minibuffer when
1149 the minibuffer becomes active to read a file name.  This serves two
1150 purposes: it shows you what the default is, so that you can type a
1151 relative file name and know with certainty what it will mean, and it
1152 allows you to edit the default to specify a different directory.  To
1153 inhibit the insertion of the default directory, set the variable
1154 `insert-default-directory' to `nil'.
1155
1156    Note that it is legitimate to type an absolute file name after you
1157 enter the minibuffer, ignoring the presence of the default directory
1158 name.  The final minibuffer contents may look invalid, but that is not
1159 so.  *Note Minibuffer File::.
1160
1161    `$' in a file name is used to substitute environment variables.  For
1162 example, if you have used the shell command `setenv FOO rms/hacks' to
1163 set up an environment variable named `FOO', then you can use
1164 `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
1165 `/u/rms/hacks/test.c'.  The environment variable name consists of all
1166 the alphanumeric characters after the `$'; alternatively, it may be
1167 enclosed in braces after the `$'.  Note that the `setenv' command
1168 affects Emacs only if done before Emacs is started.
1169
1170    To access a file with `$' in its name, type `$$'.  This pair is
1171 converted to a single `$' at the same time variable substitution is
1172 performed for single `$'.  The Lisp function that performs the
1173 substitution is called `substitute-in-file-name'.  The substitution is
1174 performed only on filenames read as such using the minibuffer.
1175