misc.texi 115 KB
Newer Older
Dave Love's avatar
#  
Dave Love committed
1
@c This is part of the Emacs manual.
2
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
Glenn Morris's avatar
Glenn Morris committed
3
@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
Glenn Morris's avatar
Glenn Morris committed
4
@c   Free Software Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
5 6 7 8 9
@c See file emacs.texi for copying conditions.
@iftex
@chapter Miscellaneous Commands

  This chapter contains several brief topics that do not fit anywhere
10 11 12 13 14 15 16
else: viewing ``document files'', reading netnews, running shell
commands and shell subprocesses, using a single shared Emacs for
utilities that expect to run an editor as a subprocess, printing
hardcopy, sorting text, narrowing display to part of the buffer,
editing double-column files and binary files, saving an Emacs session
for later resumption, following hyperlinks, browsing images, emulating
other editors, and various diversions and amusements.
Dave Love's avatar
#  
Dave Love committed
17 18

@end iftex
19 20 21 22 23

@ifnottex
@raisesections
@end ifnottex

24 25
@node Document View, Gnus, Calendar/Diary, Top
@section Document Viewing
26
@cindex DVI file
27 28
@cindex PDF file
@cindex PS file
29
@cindex Postscript file
30 31
@cindex DocView mode
@cindex mode, DocView
32
@cindex document viewer (DocView)
33 34
@findex doc-view-mode

35 36 37 38 39
DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript
(PS), and PDF documents.  It provides features such as slicing,
zooming, and searching inside documents.  It works by converting the
document to a set of images using the @command{gs} (GhostScript)
command, and displaying those images.
40

41
@findex doc-view-toggle-display
42
@findex doc-view-toggle-display
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
@cindex doc-view-minor-mode
  When you visit a PDF or DVI file, Emacs automatically switches to
DocView mode.  When you visit a Postscript file, Emacs switches to PS
mode, a major mode for editing Postscript files as text; however, it
also enables DocView minor mode, so you can type @kbd{C-c C-c} to view
the document with DocView.  (PDF and DVI files, unlike Postscript
files, are not usually human-editable.)  In either case, repeating
@kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView
and the file text.

  You can explicitly toggle DocView mode with the command @code{M-x
doc-view-mode}, and DocView minor mode with the command @code{M-x
doc-view-minor-mode}.

  When DocView mode starts, it displays a welcome screen and begins
formatting the file, page by page.  It displays the first page once
that has been formatted.
60 61 62

@findex doc-view-enlarge
@findex doc-view-shrink
63
@vindex doc-view-resolution
64
  When in DocView mode, you can enlarge or shrink the document with
65 66 67
@kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
(@code{doc-view-shrink}).  To specify the default size for DocView,
set or customize the variable @code{doc-view-resolution}.
68

69 70 71
  To kill the DocView buffer, type @kbd{k}
(@code{doc-view-kill-proc-and-buffer}).  To bury it, type @kbd{q}
(@code{quit-window}).
72 73

@menu
74 75 76 77
* Navigation::  Navigation inside DocView buffers.
* Searching::   Searching inside documents.
* Slicing::     Specifying which part of pages should be displayed.
* Conversion::  Influencing and triggering conversion.
78 79 80 81 82
@end menu

@node Navigation
@subsection Navigation

83
When in DocView mode, you can scroll the current page using the usual
84 85
Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
the arrow keys.
86

87 88 89 90 91 92 93 94
@vindex doc-view-continuous
  By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop
scrolling at the beginning and end of the current page, respectively.
However, if you change the variable @code{doc-view-continuous} to a
non-@code{nil} value, then @kbd{C-p} displays the previous page if you
are already at the beginning of the current page, and @kbd{C-n}
displays the next page if you are at the end of the current page.

95 96
@findex doc-view-next-page
@findex doc-view-previous-page
97 98 99 100
  You can also display the next page by typing @kbd{n}, @key{next} or
@kbd{C-x ]} (@code{doc-view-next-page}).  To display the previous
page, type @kbd{p}, @key{prior} or @kbd{C-x [}
(@code{doc-view-previous-page}).
101 102 103

@findex doc-view-scroll-up-or-next-page
@findex doc-view-scroll-down-or-previous-page
104
  The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a
105 106
convenient way to advance through the document.  It scrolls within the
current page or advances to the next.  @key{DEL} moves backwards in a
107
similar way (@code{doc-view-scroll-down-or-previous-page}).
108 109 110 111

@findex doc-view-first-page
@findex doc-view-last-page
@findex doc-view-goto-page
112 113 114 115
  To go to the first page, type @kbd{M-<}
(@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
(@code{doc-view-last-page}).  To jump to a page by its number, type
@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
116 117 118 119

@node Searching
@subsection Searching

120
While in DocView mode, you can search the file's text for a regular
121 122
expression (@pxref{Regexps}).  The interface for searching is inspired
by @code{isearch} (@pxref{Incremental Search}).
123 124 125 126

@findex doc-view-search
@findex doc-view-search-backward
@findex doc-view-show-tooltip
127 128 129 130 131 132 133 134 135 136 137 138 139
  To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
@kbd{C-r} (@code{doc-view-search-backward}).  This reads a regular
expression using a minibuffer, then echoes the number of matches found
within the document.  You can move forward and back among the matches
by typing @kbd{C-s} and @kbd{C-r}.  DocView mode has no way to show
the match inside the page image; instead, it displays a tooltip (at
the mouse position) listing all matching lines in the current page.
To force display of this tooltip, type @kbd{C-t}
(@code{doc-view-show-tooltip}).

  To start a new search, use the search command with a prefix
argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
for a backward search.
140 141 142 143

@node Slicing
@subsection Slicing

144 145 146
Documents often have wide margins for printing.  They are annoying
when reading the document on the screen, because they use up screen
space and can cause inconvenient scrolling.
147 148 149

@findex doc-view-set-slice
@findex doc-view-set-slice-using-mouse
150
  With DocView you can hide these margins by selecting a @dfn{slice}
151 152 153 154
of pages to display.  A slice is a rectangle within the page area;
once you specify a slice in DocView, it applies to whichever page you
look at.

155
  To specify the slice numerically, type @kbd{s s}
156 157 158 159 160 161 162 163
(@code{doc-view-set-slice}); then enter the top left pixel position
and the slice's width and height.
@c ??? how does this work?
                
  A more convenient graphical way to specify the slice is with @kbd{s
m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
select the slice.
@c ??? How does this work?
164 165

@findex doc-view-reset-slice
166
  To cancel the selected slice, type @kbd{s r}
167 168
(@code{doc-view-reset-slice}).  Then DocView shows the entire page
including its entire margins.
169 170 171 172

@node Conversion
@subsection Conversion

173
@vindex doc-view-cache-directory
174
@findex doc-view-clear-cache
175 176 177 178
For efficiency, DocView caches the images produced by @command{gs}.
The name of this directory is given by the variable
@code{doc-view-cache-directory}.  You can clear the cache directory by
typing @code{M-x doc-view-clear-cache}.
179 180 181

@findex doc-view-kill-proc
@findex doc-view-kill-proc-and-buffer
182 183 184
  To force a reconversion of the currently viewed document, type
@kbd{r} or @kbd{g} (@code{revert-buffer}).  To kill the converter
process associated with the current buffer, type @kbd{K}
185 186 187
(@code{doc-view-kill-proc}).  The command @kbd{k}
(@code{doc-view-kill-proc-and-buffer}) kills the converter process and
the DocView buffer.
188

189
  The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
190 191
(@code{doc-view-shrink}) need to reconvert the document at the new
size.  The current page is converted first.
192 193

@node Gnus, Shell, Document View, Top
Dave Love's avatar
#  
Dave Love committed
194 195 196 197 198 199 200 201
@section Gnus
@cindex Gnus
@cindex reading netnews

Gnus is an Emacs package primarily designed for reading and posting
Usenet news.  It can also be used to read and respond to messages from a
number of other sources---mail, remote directories, digests, and so on.
Here we introduce Gnus and describe several basic features.
202
@ifnottex
Dave Love's avatar
#  
Dave Love committed
203
For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
204
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
205
@iftex
206
For full details on Gnus, type @kbd{C-h i} and then select the Gnus
Dave Love's avatar
#  
Dave Love committed
207 208 209 210 211 212 213
manual.
@end iftex

@findex gnus
To start Gnus, type @kbd{M-x gnus @key{RET}}.

@menu
214 215 216
* Buffers of Gnus::     The group, summary, and article buffers.
* Gnus Startup::        What you should know about starting Gnus.
* Summary of Gnus::     A short description of the basic Gnus commands.
Dave Love's avatar
#  
Dave Love committed
217 218 219 220 221
@end menu

@node Buffers of Gnus
@subsection Gnus Buffers

Richard M. Stallman's avatar
Richard M. Stallman committed
222 223 224 225
Unlike most Emacs packages, Gnus uses several buffers to display
information and to receive commands.  The three Gnus buffers users use
most are the @dfn{group buffer}, the @dfn{summary buffer} and the
@dfn{article buffer}.
Dave Love's avatar
#  
Dave Love committed
226

Richard M. Stallman's avatar
Richard M. Stallman committed
227 228 229 230
The @dfn{group buffer} contains a list of newsgroups.  This is the
first buffer Gnus displays when it starts up.  It normally displays
only the groups to which you subscribe and that contain unread
articles.  Use this buffer to select a specific group.
Dave Love's avatar
#  
Dave Love committed
231 232 233 234 235 236 237 238 239

The @dfn{summary buffer} lists one line for each article in a single
group.  By default, the author, the subject and the line number are
displayed for each article, but this is customizable, like most aspects
of Gnus display.  The summary buffer is created when you select a group
in the group buffer, and is killed when you exit the group.  Use this
buffer to select an article.

The @dfn{article buffer} displays the article.  In normal Gnus usage,
Richard M. Stallman's avatar
Richard M. Stallman committed
240 241 242 243
you see this buffer but you don't select it---all useful
article-oriented commands work in the summary buffer.  But you can
select the article buffer, and execute all Gnus commands from that
buffer, if you want to.
Dave Love's avatar
#  
Dave Love committed
244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272

@node Gnus Startup
@subsection When Gnus Starts Up

At startup, Gnus reads your @file{.newsrc} news initialization file
and attempts to communicate with the local news server, which is a
repository of news articles.  The news server need not be the same
computer you are logged in on.

If you start Gnus and connect to the server, but do not see any
newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get
a listing of all the groups.  Then type @kbd{u} to toggle
subscription to groups.

The first time you start Gnus, Gnus subscribes you to a few selected
groups.  All other groups start out as @dfn{killed groups} for you; you
can list them with @kbd{A k}.  All new groups that subsequently come to
exist at the news server become @dfn{zombie groups} for you; type @kbd{A
z} to list them.  You can subscribe to a group shown in these lists
using the @kbd{u} command.

When you quit Gnus with @kbd{q}, it automatically records in your
@file{.newsrc} and @file{.newsrc.eld} initialization files the
subscribed or unsubscribed status of all groups.  You should normally
not edit these files manually, but you may if you know how.

@node Summary of Gnus
@subsection Summary of Gnus Commands

273
Reading news is a two-step process:
Dave Love's avatar
#  
Dave Love committed
274 275 276 277 278 279 280 281 282 283 284

@enumerate
@item
Choose a group in the group buffer.

@item
Select articles from the summary buffer.  Each article selected is
displayed in the article buffer in a large window, below the summary
buffer in its small window.
@end enumerate

Richard M. Stallman's avatar
Richard M. Stallman committed
285 286 287
  Each Gnus buffer has its own special commands; the meanings of any
given key in the various Gnus buffers are usually analogous, even if
not identical.  Here are commands for the group and summary buffers:
Dave Love's avatar
#  
Dave Love committed
288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339

@table @kbd
@kindex q @r{(Gnus Group mode)}
@findex gnus-group-exit
@item q
In the group buffer, update your @file{.newsrc} initialization file
and quit Gnus.

In the summary buffer, exit the current group and return to the
group buffer.  Thus, typing @kbd{q} twice quits Gnus.

@kindex L @r{(Gnus Group mode)}
@findex gnus-group-list-all-groups
@item L
In the group buffer, list all the groups available on your news
server (except those you have killed).  This may be a long list!

@kindex l @r{(Gnus Group mode)}
@findex gnus-group-list-groups
@item l
In the group buffer, list only the groups to which you subscribe and
which contain unread articles.

@kindex u @r{(Gnus Group mode)}
@findex gnus-group-unsubscribe-current-group
@cindex subscribe groups
@cindex unsubscribe groups
@item u
In the group buffer, unsubscribe from (or subscribe to) the group listed
in the line that point is on.  When you quit Gnus by typing @kbd{q},
Gnus lists in your @file{.newsrc} file which groups you have subscribed
to.  The next time you start Gnus, you won't see this group,
because Gnus normally displays only subscribed-to groups.

@kindex C-k @r{(Gnus)}
@findex gnus-group-kill-group
@item C-k
In the group buffer, ``kill'' the current line's group---don't
even list it in @file{.newsrc} from now on.  This affects future
Gnus sessions as well as the present session.

When you quit Gnus by typing @kbd{q}, Gnus writes information
in the file @file{.newsrc} describing all newsgroups except those you
have ``killed.''

@kindex SPC @r{(Gnus)}
@findex gnus-group-read-group
@item @key{SPC}
In the group buffer, select the group on the line under the cursor
and display the first unread article in that group.

@need 1000
340
In the summary buffer,
Dave Love's avatar
#  
Dave Love committed
341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409

@itemize @bullet
@item
Select the article on the line under the cursor if none is selected.

@item
Scroll the text of the selected article (if there is one).

@item
Select the next unread article if at the end of the current article.
@end itemize

Thus, you can move through all the articles by repeatedly typing @key{SPC}.

@kindex DEL @r{(Gnus)}
@item @key{DEL}
In the group buffer, move point to the previous group containing
unread articles.

@findex gnus-summary-prev-page
In the summary buffer, scroll the text of the article backwards.

@kindex n @r{(Gnus)}
@findex gnus-group-next-unread-group
@findex gnus-summary-next-unread-article
@item n
Move point to the next unread group, or select the next unread article.

@kindex p @r{(Gnus)}
@findex gnus-group-prev-unread-group
@findex gnus-summary-prev-unread-article
@item p
Move point to the previous unread group, or select the previous
unread article.

@kindex C-n @r{(Gnus Group mode)}
@findex gnus-group-next-group
@kindex C-p @r{(Gnus Group mode)}
@findex gnus-group-prev-group
@kindex C-n @r{(Gnus Summary mode)}
@findex gnus-summary-next-subject
@kindex C-p @r{(Gnus Summary mode)}
@findex gnus-summary-prev-subject
@item C-n
@itemx C-p
Move point to the next or previous item, even if it is marked as read.
This does not select the article or group on that line.

@kindex s @r{(Gnus Summary mode)}
@findex gnus-summary-isearch-article
@item s
In the summary buffer, do an incremental search of the current text in
the article buffer, just as if you switched to the article buffer and
typed @kbd{C-s}.

@kindex M-s @r{(Gnus Summary mode)}
@findex gnus-summary-search-article-forward
@item M-s @var{regexp} @key{RET}
In the summary buffer, search forward for articles containing a match
for @var{regexp}.

@end table

@ignore
@node Where to Look
@subsection Where to Look Further

@c Too many references to the name of the manual if done with xref in TeX!
Gnus is powerful and customizable.  Here are references to a few
410
@ifnottex
Dave Love's avatar
#  
Dave Love committed
411 412
additional topics:

413
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
@iftex
additional topics in @cite{The Gnus Manual}:

@itemize @bullet
@item
Follow discussions on specific topics.@*
See section ``Threading.''

@item
Read digests.  See section ``Document Groups.''

@item
Refer to and jump to the parent of the current article.@*
See section ``Finding the Parent.''

@item
Refer to articles by using Message-IDs included in the messages.@*
See section ``Article Keymap.''

@item
Save articles.  See section ``Saving Articles.''

@item
Have Gnus score articles according to various criteria, like author
name, subject, or string in the body of the articles.@*
See section ``Scoring.''

@item
Send an article to a newsgroup.@*
See section ``Composing Messages.''
@end itemize
@end iftex
446
@ifnottex
Dave Love's avatar
#  
Dave Love committed
447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469
@itemize @bullet
@item
Follow discussions on specific topics.@*
@xref{Threading, , Reading Based on Conversation Threads,
gnus, The Gnus Manual}.

@item
Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}.

@item
Refer to and jump to the parent of the current article.@*
@xref{Finding the Parent, , , gnus, The Gnus Manual}.

@item
Refer to articles by using Message-IDs included in the messages.@*
@xref{Article Keymap, , , gnus, The Gnus Manual}.

@item
Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}.

@item
Have Gnus score articles according to various criteria, like author
name, subject, or string in the body of the articles.@*
470
@xref{Scoring, , , gnus, The Gnus Manual}.
Dave Love's avatar
#  
Dave Love committed
471 472 473 474 475

@item
Send an article to a newsgroup.@*
@xref{Composing Messages, , , gnus, The Gnus Manual}.
@end itemize
476
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
477 478 479 480 481 482 483 484
@end ignore

@node Shell, Emacs Server, Gnus, Top
@section Running Shell Commands from Emacs
@cindex subshell
@cindex shell commands

  Emacs has commands for passing single command lines to inferior shell
Dave Love's avatar
Dave Love committed
485
processes; it can also run a shell interactively with input and output
486
to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal
Dave Love's avatar
Dave Love committed
487 488
emulator window.

Dave Love's avatar
#  
Dave Love committed
489 490 491 492 493 494 495 496
@table @kbd
@item M-! @var{cmd} @key{RET}
Run the shell command line @var{cmd} and display the output
(@code{shell-command}).
@item M-| @var{cmd} @key{RET}
Run the shell command line @var{cmd} with region contents as input;
optionally replace the region with the output
(@code{shell-command-on-region}).
497 498 499
@item M-& @var{cmd} @key{RET}
Run the shell command line @var{cmd} asynchronously, and display the
output (@code{async-shell-command}).
Dave Love's avatar
#  
Dave Love committed
500 501 502
@item M-x shell
Run a subshell with input and output through an Emacs buffer.
You can then give commands interactively.
Dave Love's avatar
Dave Love committed
503 504 505 506
@item M-x term
Run a subshell with input and output through an Emacs buffer.
You can then give commands interactively.
Full terminal emulation is available.
Dave Love's avatar
#  
Dave Love committed
507 508
@end table

Richard M. Stallman's avatar
Richard M. Stallman committed
509 510 511 512
  @kbd{M-x eshell} invokes a shell implemented entirely in Emacs.  It
is documented in a separate manual.  @xref{Top,Eshell,Eshell, eshell,
Eshell: The Emacs Shell}.

Dave Love's avatar
#  
Dave Love committed
513 514 515 516
@menu
* Single Shell::           How to run one shell command and return.
* Interactive Shell::      Permanent shell taking input via Emacs.
* Shell Mode::             Special Emacs commands used with permanent shell.
517
* Shell Prompts::          Two ways to recognize shell prompts.
Dave Love's avatar
#  
Dave Love committed
518
* History: Shell History.  Repeating previous commands in a shell buffer.
519
* Directory Tracking::     Keeping track when the subshell changes directory.
Dave Love's avatar
#  
Dave Love committed
520
* Options: Shell Options.  Options for customizing Shell mode.
Dave Love's avatar
Dave Love committed
521 522 523
* Terminal emulator::      An Emacs window as a terminal emulator.
* Term Mode::              Special Emacs commands used in Term mode.
* Paging in Term::         Paging in the terminal emulator.
Dave Love's avatar
#  
Dave Love committed
524
* Remote Host::            Connecting to another computer.
525
* Serial Terminal::        Connecting to a serial port.
Dave Love's avatar
#  
Dave Love committed
526 527 528 529 530 531 532 533 534 535
@end menu

@node Single Shell
@subsection Single Shell Commands

@kindex M-!
@findex shell-command
  @kbd{M-!} (@code{shell-command}) reads a line of text using the
minibuffer and executes it as a shell command in a subshell made just
for that command.  Standard input for the command comes from the null
536 537 538
device.  If the shell command produces any output, the output appears
either in the echo area (if it is short), or in an Emacs buffer named
@samp{*Shell Command Output*}, which is displayed in another window
539 540 541 542 543 544 545 546 547
but not selected (if the output is long).

  For instance, one way to decompress a file @file{foo.gz} from Emacs
is to type @kbd{M-! gunzip foo.gz @key{RET}}.  That shell command
normally creates the file @file{foo} and produces no terminal output.

  A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal
output into the current buffer instead of a separate buffer.  It puts
point before the output, and sets the mark after the output.  For
Richard M. Stallman's avatar
Richard M. Stallman committed
548
instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
549
uncompressed equivalent of @file{foo.gz} into the current buffer.
Dave Love's avatar
#  
Dave Love committed
550 551 552 553

  If the shell command line ends in @samp{&}, it runs asynchronously.
For a synchronous shell command, @code{shell-command} returns the
command's exit status (0 means success), when it is called from a Lisp
554
program.  You do not get any status information for an asynchronous
Richard M. Stallman's avatar
Richard M. Stallman committed
555
command, since it hasn't finished yet when @code{shell-command} returns.
Dave Love's avatar
#  
Dave Love committed
556

557 558 559 560 561
  You can also type @kbd{M-&} (@code{async-shell-command}) to execute
a shell command asynchronously.  This behaves exactly like calling
@code{shell-command} with @samp{&}, except that you do not need to add
the @samp{&} to the shell command line.

Dave Love's avatar
#  
Dave Love committed
562 563 564 565
@kindex M-|
@findex shell-command-on-region
  @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
passes the contents of the region as the standard input to the shell
Richard M. Stallman's avatar
Richard M. Stallman committed
566 567 568 569
command, instead of no input.  With a numeric argument, meaning insert
the output in the current buffer, it deletes the old region and the
output replaces it as the contents of the region.  It returns the
command's exit status, like @kbd{M-!}.
Dave Love's avatar
#  
Dave Love committed
570

571 572
  One use for @kbd{M-|} is to run @code{gpg} to see what keys are in
the buffer.  For instance, if the buffer contains a GPG key, type
Richard M. Stallman's avatar
Richard M. Stallman committed
573 574 575 576
@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to
the @code{gpg} program.  That program will ignore everything except
the encoded keys, and will output a list of the keys the buffer
contains.
577

Dave Love's avatar
#  
Dave Love committed
578
@vindex shell-file-name
Richard M. Stallman's avatar
Richard M. Stallman committed
579 580 581 582 583
  Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify
the shell to use.  This variable is initialized based on your
@env{SHELL} environment variable when Emacs is started.  If the file
name is relative, Emacs searches the directories in the list
@code{exec-path}; this list is initialized based on the environment
584 585 586
variable @env{PATH} when Emacs is started.  Your init file can
override either or both of these default initializations (@pxref{Init
File}).
Dave Love's avatar
#  
Dave Love committed
587

588
  Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete,
589
unless you end the command with @samp{&} to make it asynchronous.  To
590
stop waiting, type @kbd{C-g} to quit; that terminates the shell
Dave Love's avatar
#  
Dave Love committed
591
command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
Richard M. Stallman's avatar
Richard M. Stallman committed
592
normally generates in the shell.  Emacs then waits until the command
593 594 595 596 597 598 599
actually terminates.  If the shell command doesn't stop (because it
ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends
the command a @code{SIGKILL} signal which is impossible to ignore.

  Asynchronous commands ending in @samp{&} feed their output into
the buffer @samp{*Async Shell Command*}.  Output arrives in that
buffer regardless of whether it is visible in a window.
Dave Love's avatar
#  
Dave Love committed
600 601

  To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
602
@kbd{C-x @key{RET} c} immediately beforehand.  @xref{Communication Coding}.
Dave Love's avatar
#  
Dave Love committed
603 604

@vindex shell-command-default-error-buffer
Richard M. Stallman's avatar
Richard M. Stallman committed
605 606 607 608 609
  Error output from these commands is normally intermixed with the
regular output.  But if the variable
@code{shell-command-default-error-buffer} has a string as value, and
it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output
before point in that buffer.
Dave Love's avatar
#  
Dave Love committed
610 611 612 613 614

@node Interactive Shell
@subsection Interactive Inferior Shell

@findex shell
615 616 617 618 619 620 621
  To run a subshell interactively, use @kbd{M-x shell}.  This creates
(or reuses) a buffer named @samp{*shell*} and runs a subshell with
input coming from and output going to that buffer.  That is to say,
any ``terminal output'' from the subshell goes into the buffer,
advancing point, and any ``terminal input'' for the subshell comes
from text in the buffer.  To give input to the subshell, go to the end
of the buffer and type the input, terminated by @key{RET}.
Dave Love's avatar
#  
Dave Love committed
622 623 624 625 626 627 628

  Emacs does not wait for the subshell to do anything.  You can switch
windows or buffers and edit them while the shell is waiting, or while it is
running a command.  Output from the subshell waits until Emacs has time to
process it; this happens whenever Emacs is waiting for keyboard input or
for time to elapse.

629 630 631 632 633 634 635
@cindex @code{comint-highlight-input} face
@cindex @code{comint-highlight-prompt} face
  Input lines, once you submit them, are displayed using the face
@code{comint-highlight-input}, and prompts are displayed using the
face @code{comint-highlight-prompt}.  This makes it easier to see
previous input lines in the buffer.  @xref{Faces}.

Richard M. Stallman's avatar
Richard M. Stallman committed
636 637 638 639
  To make multiple subshells, you can invoke @kbd{M-x shell} with a
prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
name and create (or reuse) a subshell in that buffer.  You can also
rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
Richard M. Stallman's avatar
Richard M. Stallman committed
640 641
create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
Subshells in different buffers run independently and in parallel.
Dave Love's avatar
#  
Dave Love committed
642 643

@vindex explicit-shell-file-name
644
@cindex environment variables for subshells
Gerd Moellmann's avatar
Gerd Moellmann committed
645 646
@cindex @env{ESHELL} environment variable
@cindex @env{SHELL} environment variable
Dave Love's avatar
#  
Dave Love committed
647
  The file name used to load the subshell is the value of the variable
648 649 650 651 652 653 654 655
@code{explicit-shell-file-name}, if that is non-@code{nil}.
Otherwise, the environment variable @env{ESHELL} is used, or the
environment variable @env{SHELL} if there is no @env{ESHELL}.  If the
file name specified is relative, the directories in the list
@code{exec-path} are searched; this list is initialized based on the
environment variable @env{PATH} when Emacs is started.  Your init file
can override either or both of these default initializations.
(@pxref{Init File}).
Dave Love's avatar
#  
Dave Love committed
656

657 658 659 660
  Emacs sends the new shell the contents of the file
@file{~/.emacs_@var{shellname}} as input, if it exists, where
@var{shellname} is the name of the file that the shell was loaded
from.  For example, if you use bash, the file sent to it is
661 662
@file{~/.emacs_bash}.  If this file is not found, Emacs tries to fallback
on @file{~/.emacs.d/init_@var{shellname}.sh}.
663

Dave Love's avatar
#  
Dave Love committed
664
  To specify a coding system for the shell, you can use the command
Richard M. Stallman's avatar
Richard M. Stallman committed
665 666 667 668
@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}.  You can
also change the coding system for a running subshell by typing
@kbd{C-x @key{RET} p} in the shell buffer.  @xref{Communication
Coding}.
Dave Love's avatar
#  
Dave Love committed
669

670
@cindex @env{INSIDE_EMACS} environment variable
671 672
  Emacs sets the environment variable @env{INSIDE_EMACS} in the
subshell to a comma-separated list including the Emacs version.
673 674
Programs can check this variable to determine whether they are running
inside an Emacs subshell.
675

676
@cindex @env{EMACS} environment variable
677
  Emacs also sets the @env{EMACS} environment variable (to @code{t}) if
678 679 680
it is not already defined.  @strong{Warning:} This environment
variable is deprecated.  Programs that check this variable should be
changed to check @env{INSIDE_EMACS} instead.
Dave Love's avatar
#  
Dave Love committed
681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696

@node Shell Mode
@subsection Shell Mode
@cindex Shell mode
@cindex mode, Shell

  Shell buffers use Shell mode, which defines several special keys
attached to the @kbd{C-c} prefix.  They are chosen to resemble the usual
editing and job control characters present in shells that are not under
Emacs, except that you must type @kbd{C-c} first.  Here is a complete list
of the special key bindings of Shell mode:

@table @kbd
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
697
At end of buffer send line as input; otherwise, copy current line to
Richard M. Stallman's avatar
Richard M. Stallman committed
698 699 700 701
end of buffer and send it (@code{comint-send-input}).  Copying a line
in this way omits any prompt at the beginning of the line (text output
by programs preceding your input).  @xref{Shell Prompts}, for how
Shell mode recognizes prompts.
Dave Love's avatar
#  
Dave Love committed
702 703 704 705 706 707 708 709 710 711 712

@item @key{TAB}
@kindex TAB @r{(Shell mode)}
@findex comint-dynamic-complete
Complete the command name or file name before point in the shell buffer
(@code{comint-dynamic-complete}).  @key{TAB} also completes history
references (@pxref{History References}) and environment variable names.

@vindex shell-completion-fignore
@vindex comint-completion-fignore
The variable @code{shell-completion-fignore} specifies a list of file
713 714 715
name extensions to ignore in Shell mode completion.  The default
setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to
ignore file names ending in @samp{~}, @samp{#} or @samp{%}.  Other
Dave Love's avatar
#  
Dave Love committed
716 717 718 719 720 721 722 723 724 725 726 727 728
related Comint modes use the variable @code{comint-completion-fignore}
instead.

@item M-?
@kindex M-? @r{(Shell mode)}
@findex comint-dynamic-list-filename@dots{}
Display temporarily a list of the possible completions of the file name
before point in the shell buffer
(@code{comint-dynamic-list-filename-completions}).

@item C-d
@kindex C-d @r{(Shell mode)}
@findex comint-delchar-or-maybe-eof
729
Either delete a character or send @acronym{EOF}
Dave Love's avatar
#  
Dave Love committed
730
(@code{comint-delchar-or-maybe-eof}).  Typed at the end of the shell
731
buffer, @kbd{C-d} sends @acronym{EOF} to the subshell.  Typed at any other
Dave Love's avatar
#  
Dave Love committed
732 733 734 735
position in the buffer, @kbd{C-d} deletes a character as usual.

@item C-c C-a
@kindex C-c C-a @r{(Shell mode)}
736
@findex comint-bol-or-process-mark
Dave Love's avatar
#  
Dave Love committed
737
Move to the beginning of the line, but after the prompt if any
738 739 740 741 742 743
(@code{comint-bol-or-process-mark}).  If you repeat this command twice
in a row, the second time it moves back to the process mark, which is
the beginning of the input that you have not yet sent to the subshell.
(Normally that is the same place---the end of the prompt on this
line---but after @kbd{C-c @key{SPC}} the process mark may be in a
previous line.)
Dave Love's avatar
#  
Dave Love committed
744 745 746 747 748 749 750 751 752 753 754 755

@item C-c @key{SPC}
Accumulate multiple lines of input, then send them together.  This
command inserts a newline before point, but does not send the preceding
text as input to the subshell---at least, not yet.  Both lines, the one
before this newline and the one after, will be sent together (along with
the newline that separates them), when you type @key{RET}.

@item C-c C-u
@kindex C-c C-u @r{(Shell mode)}
@findex comint-kill-input
Kill all text pending at end of buffer to be sent as input
756 757
(@code{comint-kill-input}).  If point is not at end of buffer,
this only kills the part of this text that precedes point.
Dave Love's avatar
#  
Dave Love committed
758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785

@item C-c C-w
@kindex C-c C-w @r{(Shell mode)}
Kill a word before point (@code{backward-kill-word}).

@item C-c C-c
@kindex C-c C-c @r{(Shell mode)}
@findex comint-interrupt-subjob
Interrupt the shell or its current subjob if any
(@code{comint-interrupt-subjob}).  This command also kills
any shell input pending in the shell buffer and not yet sent.

@item C-c C-z
@kindex C-c C-z @r{(Shell mode)}
@findex comint-stop-subjob
Stop the shell or its current subjob if any (@code{comint-stop-subjob}).
This command also kills any shell input pending in the shell buffer and
not yet sent.

@item C-c C-\
@findex comint-quit-subjob
@kindex C-c C-\ @r{(Shell mode)}
Send quit signal to the shell or its current subjob if any
(@code{comint-quit-subjob}).  This command also kills any shell input
pending in the shell buffer and not yet sent.

@item C-c C-o
@kindex C-c C-o @r{(Shell mode)}
Miles Bader's avatar
Miles Bader committed
786 787 788 789 790 791 792 793 794 795 796 797 798
@findex comint-delete-output
Delete the last batch of output from a shell command
(@code{comint-delete-output}).  This is useful if a shell command spews
out lots of output that just gets in the way.  This command used to be
called @code{comint-kill-output}.

@item C-c C-s
@kindex C-c C-s @r{(Shell mode)}
@findex comint-write-output
Write the last batch of output from a shell command to a file
(@code{comint-write-output}).  With a prefix argument, the file is
appended to instead.  Any prompt at the end of the output is not
written.
Dave Love's avatar
#  
Dave Love committed
799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837

@item C-c C-r
@itemx C-M-l
@kindex C-c C-r @r{(Shell mode)}
@kindex C-M-l @r{(Shell mode)}
@findex comint-show-output
Scroll to display the beginning of the last batch of output at the top
of the window; also move the cursor there (@code{comint-show-output}).

@item C-c C-e
@kindex C-c C-e @r{(Shell mode)}
@findex comint-show-maximum-output
Scroll to put the end of the buffer at the bottom of the window
(@code{comint-show-maximum-output}).

@item C-c C-f
@kindex C-c C-f @r{(Shell mode)}
@findex shell-forward-command
@vindex shell-command-regexp
Move forward across one shell command, but not beyond the current line
(@code{shell-forward-command}).  The variable @code{shell-command-regexp}
specifies how to recognize the end of a command.

@item C-c C-b
@kindex C-c C-b @r{(Shell mode)}
@findex shell-backward-command
Move backward across one shell command, but not beyond the current line
(@code{shell-backward-command}).

@item M-x dirs
Ask the shell what its current directory is, so that Emacs can agree
with the shell.

@item M-x send-invisible @key{RET} @var{text} @key{RET}
@findex send-invisible
Send @var{text} as input to the shell, after reading it without
echoing.  This is useful when a shell command runs a program that asks
for a password.

838 839 840
Please note that Emacs will not echo passwords by default.  If you
really want them to be echoed, evaluate the following Lisp
expression:
Dave Love's avatar
#  
Dave Love committed
841 842

@example
843 844
(remove-hook 'comint-output-filter-functions
             'comint-watch-for-password-prompt)
Dave Love's avatar
#  
Dave Love committed
845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884
@end example

@item M-x comint-continue-subjob
@findex comint-continue-subjob
Continue the shell process.  This is useful if you accidentally suspend
the shell process.@footnote{You should not suspend the shell process.
Suspending a subjob of the shell is a completely different matter---that
is normal practice, but you must use the shell to continue the subjob;
this command won't do it.}

@item M-x comint-strip-ctrl-m
@findex comint-strip-ctrl-m
Discard all control-M characters from the current group of shell output.
The most convenient way to use this command is to make it run
automatically when you get output from the subshell.  To do that,
evaluate this Lisp expression:

@example
(add-hook 'comint-output-filter-functions
          'comint-strip-ctrl-m)
@end example

@item M-x comint-truncate-buffer
@findex comint-truncate-buffer
This command truncates the shell buffer to a certain maximum number of
lines, specified by the variable @code{comint-buffer-maximum-size}.
Here's how to do this automatically each time you get output from the
subshell:

@example
(add-hook 'comint-output-filter-functions
          'comint-truncate-buffer)
@end example
@end table

@cindex Comint mode
@cindex mode, Comint
  Shell mode is a derivative of Comint mode, a general-purpose mode for
communicating with interactive subprocesses.  Most of the features of
Shell mode actually come from Comint mode, as you can see from the
885 886
command names listed above.  The special features of Shell mode include
the directory tracking feature, and a few user commands.
Dave Love's avatar
#  
Dave Love committed
887 888 889 890 891 892 893 894 895

  Other Emacs features that use variants of Comint mode include GUD
(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).

@findex comint-run
  You can use @kbd{M-x comint-run} to execute any program of your choice
in a subprocess using unmodified Comint mode---without the
specializations of Shell mode.

896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934
@node Shell Prompts
@subsection Shell Prompts

@vindex shell-prompt-pattern
@vindex comint-prompt-regexp
@vindex comint-use-prompt-regexp
@cindex prompt, shell
  A prompt is text output by a program to show that it is ready to
accept new user input.  Normally, Comint mode (and thus Shell mode)
considers the prompt to be any text output by a program at the
beginning of an input line.  However, if the variable
@code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode
uses a regular expression to recognize prompts.  In Shell mode,
@code{shell-prompt-pattern} specifies the regular expression.

  The value of @code{comint-use-prompt-regexp} also affects many
motion and paragraph commands.  If the value is non-@code{nil}, the
general Emacs motion commands behave as they normally do in buffers
without special text properties.  However, if the value is @code{nil},
the default, then Comint mode divides the buffer into two types of
``fields'' (ranges of consecutive characters having the same
@code{field} text property): input and output.  Prompts are part of
the output.  Most Emacs motion commands do not cross field boundaries,
unless they move over multiple lines.  For instance, when point is in
input on the same line as a prompt, @kbd{C-a} puts point at the
beginning of the input if @code{comint-use-prompt-regexp} is
@code{nil} and at the beginning of the line otherwise.

  In Shell mode, only shell prompts start new paragraphs.  Thus, a
paragraph consists of a prompt and the input and output that follow
it.  However, if @code{comint-use-prompt-regexp} is @code{nil}, the
default, most paragraph commands do not cross field boundaries.  This
means that prompts, ranges of input, and ranges of non-prompt output
behave mostly like separate paragraphs; with this setting, numeric
arguments to most paragraph commands yield essentially undefined
behavior.  For the purpose of finding paragraph boundaries, Shell mode
uses @code{shell-prompt-pattern}, regardless of
@code{comint-use-prompt-regexp}.

Dave Love's avatar
#  
Dave Love committed
935 936 937 938
@node Shell History
@subsection Shell Command History

  Shell buffers support three ways of repeating earlier commands.  You
939 940 941 942 943 944
can use keys like those used for the minibuffer history; these work
much as they do in the minibuffer, inserting text from prior commands
while point remains always at the end of the buffer.  You can move
through the buffer to previous inputs in their original place, then
resubmit them or copy them to the end.  Or you can use a
@samp{!}-style history reference.
Dave Love's avatar
#  
Dave Love committed
945 946 947 948 949 950 951 952 953 954 955 956 957 958

@menu
* Ring: Shell Ring.             Fetching commands from the history list.
* Copy: Shell History Copying.  Moving to a command and then copying it.
* History References::          Expanding @samp{!}-style history references.
@end menu

@node Shell Ring
@subsubsection Shell History Ring

@table @kbd
@findex comint-previous-input
@kindex M-p @r{(Shell mode)}
@item M-p
959
@itemx C-@key{UP}
Dave Love's avatar
#  
Dave Love committed
960 961 962 963 964
Fetch the next earlier old shell command.

@kindex M-n @r{(Shell mode)}
@findex comint-next-input
@item M-n
965
@itemx C-@key{DOWN}
Dave Love's avatar
#  
Dave Love committed
966 967 968
Fetch the next later old shell command.

@kindex M-r @r{(Shell mode)}
969 970 971
@findex comint-history-isearch-backward-regexp
@item M-r
Begin an incremental regexp search of old shell commands.
Dave Love's avatar
#  
Dave Love committed
972

973 974
@item C-c C-x
@kindex C-c C-x @r{(Shell mode)}
Dave Love's avatar
#  
Dave Love committed
975 976
@findex comint-get-next-from-history
Fetch the next subsequent command from the history.
977

978 979
@item C-c .
@kindex C-c . @r{(Shell mode)}
980 981
@findex comint-input-previous-argument
Fetch one argument from an old shell command.
982 983 984 985 986 987

@item C-c C-l
@kindex C-c C-l @r{(Shell mode)}
@findex comint-dynamic-list-input-ring
Display the buffer's history of shell commands in another window
(@code{comint-dynamic-list-input-ring}).
Dave Love's avatar
#  
Dave Love committed
988 989 990 991 992 993 994 995
@end table

  Shell buffers provide a history of previously entered shell commands.  To
reuse shell commands from the history, use the editing commands @kbd{M-p},
@kbd{M-n}, @kbd{M-r} and @kbd{M-s}.  These work just like the minibuffer
history commands except that they operate on the text at the end of the
shell buffer, where you would normally insert text to send to the shell.

996 997 998 999 1000 1001 1002
  @kbd{M-p} fetches an earlier shell command to the end of the shell
buffer.  Successive use of @kbd{M-p} fetches successively earlier
shell commands, each replacing any text that was already present as
potential shell input.  @kbd{M-n} does likewise except that it finds
successively more recent shell commands from the buffer.
@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like
@kbd{M-n}.
Dave Love's avatar
#  
Dave Love committed
1003

1004 1005 1006 1007 1008 1009 1010 1011 1012
  The history search command @kbd{M-r} begins an incremental regular
expression search of previous shell commands.  After typing @kbd{M-r},
start typing the desired string or regular expression; the last
matching shell command will be displayed in the current line.
Incremental search commands have their usual effects---for instance,
@kbd{C-s} and @kbd{C-r} search forward and backward for the next match
(@pxref{Incremental Search}).  When you find the desired input, type
@key{RET} to terminate the search.  This puts the input in the command
line.  Any partial input you were composing before navigating the
1013 1014
history list is restored when you go to the beginning or end of the
history ring.
Dave Love's avatar
#  
Dave Love committed
1015 1016 1017 1018 1019 1020 1021 1022 1023

  Often it is useful to reexecute several successive shell commands that
were previously executed in sequence.  To do this, first find and
reexecute the first command of the sequence.  Then type @kbd{C-c C-x};
that will fetch the following command---the one that follows the command
you just repeated.  Then type @key{RET} to reexecute this command.  You
can reexecute several successive commands by typing @kbd{C-c C-x
@key{RET}} over and over.

1024 1025 1026 1027 1028 1029 1030 1031 1032
  The command @kbd{C-c .}@: (@code{comint-input-previous-argument})
copies an individual argument from a previous command, like @kbd{ESC
.} in Bash.  The simplest use copies the last argument from the
previous shell command.  With a prefix argument @var{n}, it copies the
@var{n}th argument instead.  Repeating @kbd{C-c .} copies from an
earlier shell command instead, always using the same value of @var{n}
(don't give a prefix argument when you repeat the @kbd{C-c .}
command).

Dave Love's avatar
#  
Dave Love committed
1033 1034 1035 1036 1037 1038 1039
  These commands get the text of previous shell commands from a special
history list, not from the shell buffer itself.  Thus, editing the shell
buffer, or even killing large parts of it, does not affect the history
that these commands access.

@vindex shell-input-ring-file-name
  Some shells store their command histories in files so that you can
1040
refer to commands from previous shell sessions.  Emacs reads
Dave Love's avatar
#  
Dave Love committed
1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059
the command history file for your chosen shell, to initialize its own
command history.  The file name is @file{~/.bash_history} for bash,
@file{~/.sh_history} for ksh, and @file{~/.history} for other shells.

@node Shell History Copying
@subsubsection Shell History Copying

@table @kbd
@kindex C-c C-p @r{(Shell mode)}
@findex comint-previous-prompt
@item C-c C-p
Move point to the previous prompt (@code{comint-previous-prompt}).

@kindex C-c C-n @r{(Shell mode)}
@findex comint-next-prompt
@item C-c C-n
Move point to the following prompt (@code{comint-next-prompt}).

@kindex C-c RET @r{(Shell mode)}
1060
@findex comint-copy-old-input
Dave Love's avatar
#  
Dave Love committed
1061
@item C-c @key{RET}
1062 1063 1064 1065 1066 1067
Copy the input command at point, inserting the copy at the end of the
buffer (@code{comint-copy-old-input}).  This is useful if you move
point back to a previous command.  After you copy the command, you can
submit the copy as input with @key{RET}.  If you wish, you can edit
the copy before resubmitting it.  If you use this command on an output
line, it copies that line to the end of the buffer.
1068 1069

@item Mouse-2
1070 1071 1072 1073 1074
If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
the old input command that you click on, inserting the copy at the end
of the buffer (@code{comint-insert-input}).  If
@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is
not over old input, just yank as usual.
Dave Love's avatar
#  
Dave Love committed
1075 1076 1077
@end table

  Moving to a previous input and then copying it with @kbd{C-c
1078 1079 1080 1081 1082 1083
@key{RET}} or @kbd{Mouse-2} produces the same results---the same
buffer contents---that you would get by using @kbd{M-p} enough times
to fetch that previous input from the history list.  However, @kbd{C-c
@key{RET}} copies the text from the buffer, which can be different
from what is in the history list if you edit the input text in the
buffer after it has been sent.
Dave Love's avatar
#  
Dave Love committed
1084 1085 1086 1087 1088

@node History References
@subsubsection Shell History References
@cindex history reference

1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108
  Various shells including csh and bash support @dfn{history
references} that begin with @samp{!} and @samp{^}.  Shell mode
recognizes these constructs, and can perform the history substitution
for you.

  If you insert a history reference and type @key{TAB}, this searches
the input history for a matching command, performs substitution if
necessary, and places the result in the buffer in place of the history
reference.  For example, you can fetch the most recent command
beginning with @samp{mv} with @kbd{! m v @key{TAB}}.  You can edit the
command if you wish, and then resubmit the command to the shell by
typing @key{RET}.

@vindex comint-input-autoexpand
@findex comint-magic-space
  Shell mode can optionally expand history references in the buffer
when you send them to the shell.  To request this, set the variable
@code{comint-input-autoexpand} to @code{input}.  You can make
@key{SPC} perform history expansion by binding @key{SPC} to the
command @code{comint-magic-space}.
Dave Love's avatar
#  
Dave Love committed
1109

1110
  Shell mode recognizes history references when they follow a prompt.
1111
@xref{Shell Prompts}, for how Shell mode recognizes prompts.
1112 1113 1114 1115

@node Directory Tracking
@subsection Directory Tracking
@cindex directory tracking
Dave Love's avatar
#  
Dave Love committed
1116

1117 1118 1119 1120 1121 1122 1123 1124
@vindex shell-pushd-regexp
@vindex shell-popd-regexp
@vindex shell-cd-regexp
  Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd}
commands given to the inferior shell, so it can keep the
@samp{*shell*} buffer's default directory the same as the shell's
working directory.  It recognizes these commands syntactically, by
examining lines of input that are sent.
Dave Love's avatar
#  
Dave Love committed
1125

1126 1127 1128 1129 1130 1131 1132 1133 1134 1135
  If you use aliases for these commands, you can tell Emacs to
recognize them also.  For example, if the value of the variable
@code{shell-pushd-regexp} matches the beginning of a shell command
line, that line is regarded as a @code{pushd} command.  Change this
variable when you add aliases for @samp{pushd}.  Likewise,
@code{shell-popd-regexp} and @code{shell-cd-regexp} are used to
recognize commands with the meaning of @samp{popd} and @samp{cd}.
These commands are recognized only at the beginning of a shell command
line.

1136
@ignore  @c This seems to have been deleted long ago.
1137 1138 1139 1140
@vindex shell-set-directory-error-hook
  If Emacs gets an error while trying to handle what it believes is a
@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook
@code{shell-set-directory-error-hook} (@pxref{Hooks}).
1141
@end ignore
1142 1143 1144 1145 1146 1147 1148 1149 1150

@findex dirs
  If Emacs gets confused about changes in the current directory of the
subshell, use the command @kbd{M-x dirs} to ask the shell what its
current directory is.  This command works for shells that support the
most common command syntax; it may not work for unusual shells.

@findex dirtrack-mode
  You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an
1151 1152 1153
alternative method of tracking changes in the current directory.  This
method relies on your shell prompt containing the full current working
directory at all times.
Dave Love's avatar
#  
Dave Love committed
1154 1155 1156 1157 1158 1159 1160

@node Shell Options
@subsection Shell Mode Options

@vindex comint-scroll-to-bottom-on-input
  If the variable @code{comint-scroll-to-bottom-on-input} is
non-@code{nil}, insertion and yank commands scroll the selected window
1161
to the bottom before inserting.  The default is @code{nil}.
Dave Love's avatar
#  
Dave Love committed
1162 1163 1164

@vindex comint-scroll-show-maximum-output
  If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
1165 1166
arrival of output when point is at the end tries to scroll the last
line of text to the bottom line of the window, showing as much useful
1167 1168
text as possible.  (This mimics the scrolling behavior of most
terminals.)  The default is @code{t}.
Dave Love's avatar
#  
Dave Love committed
1169

1170 1171
@vindex comint-move-point-for-output
  By setting @code{comint-move-point-for-output}, you can opt for
Dave Love's avatar
#  
Dave Love committed
1172 1173 1174
having point jump to the end of the buffer whenever output arrives---no
matter where in the buffer point was before.  If the value is
@code{this}, point jumps in the selected window.  If the value is
1175
@code{all}, point jumps in each window that shows the Comint buffer.  If
Dave Love's avatar
#  
Dave Love committed
1176 1177 1178 1179
the value is @code{other}, point jumps in all nonselected windows that
show the current buffer.  The default value is @code{nil}, which means
point does not jump to the end.

1180 1181
@vindex comint-prompt-read-only
  If you set @code{comint-prompt-read-only}, the prompts in the Comint
1182
buffer are read-only.
1183

Dave Love's avatar
#  
Dave Love committed
1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203
@vindex comint-input-ignoredups
  The variable @code{comint-input-ignoredups} controls whether successive
identical inputs are stored in the input history.  A non-@code{nil}
value means to omit an input that is the same as the previous input.
The default is @code{nil}, which means to store each input even if it is
equal to the previous input.

@vindex comint-completion-addsuffix
@vindex comint-completion-recexact
@vindex comint-completion-autolist
  Three variables customize file name completion.  The variable
@code{comint-completion-addsuffix} controls whether completion inserts a
space or a slash to indicate a fully completed file or directory name
(non-@code{nil} means do insert a space or slash).
@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB}
to choose the shortest possible completion if the usual Emacs completion
algorithm cannot add even a single character.
@code{comint-completion-autolist}, if non-@code{nil}, says to list all
the possible completions whenever completion is not exact.

1204
@vindex shell-completion-execonly
Dave Love's avatar
#  
Dave Love committed
1205
  Command completion normally considers only executable files.
1206
If you set @code{shell-completion-execonly} to @code{nil},
Dave Love's avatar
#  
Dave Love committed
1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219
it considers nonexecutable files as well.

@findex shell-pushd-tohome
@findex shell-pushd-dextract
@findex shell-pushd-dunique
  You can configure the behavior of @samp{pushd}.  Variables control
whether @samp{pushd} behaves like @samp{cd} if no argument is given
(@code{shell-pushd-tohome}), pop rather than rotate with a numeric
argument (@code{shell-pushd-dextract}), and only add directories to the
directory stack if they are not already on it
(@code{shell-pushd-dunique}).  The values you choose should match the
underlying shell, of course.

Dave Love's avatar
Dave Love committed
1220
@node Terminal emulator
1221
@subsection Emacs Terminal Emulator
Dave Love's avatar
Dave Love committed
1222 1223
@findex term

1224 1225 1226 1227
  To run a subshell in a terminal emulator, use @kbd{M-x term}.  This
creates (or reuses) a buffer named @samp{*terminal*}, and runs a
subshell with input coming from your keyboard, and output going to
that buffer.
1228 1229 1230

  The terminal emulator uses Term mode, which has two input modes.  In
line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
Dave Love's avatar
Dave Love committed
1231

1232 1233 1234 1235
  In char mode, each character is sent directly to the inferior
subshell, as ``terminal input.''  Any ``echoing'' of your input is the
responsibility of the subshell.  The sole exception is the terminal
escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
Dave Love's avatar
Dave Love committed
1236 1237 1238
Any ``terminal output'' from the subshell goes into the buffer,
advancing point.

1239 1240 1241 1242 1243 1244 1245 1246 1247 1248
  Some programs (such as Emacs itself) need to control the appearance
on the terminal screen in detail.  They do this by sending special
control codes.  The exact control codes needed vary from terminal to
terminal, but nowadays most terminals and terminal emulators
(including @code{xterm}) understand the ANSI-standard (VT100-style)
escape sequences.  Term mode recognizes these escape sequences, and
handles each one appropriately, changing the buffer so that the
appearance of the window matches what it would be on a real terminal.
You can actually run Emacs inside an Emacs Term window.

1249
  You can use Term mode to communicate with a device connected to a
1250
serial port of your computer.  @xref{Serial Terminal}.
1251 1252

  The file name used to load the subshell is determined the same way
1253
as for Shell mode.  To make multiple terminal emulators, rename the
1254
buffer @samp{*terminal*} to something different using @kbd{M-x
1255 1256 1257 1258 1259 1260
rename-uniquely}, just as with Shell mode.

  Unlike Shell mode, Term mode does not track the current directory by
examining your input.  But some shells can tell Term what the current
directory is.  This is done automatically by @code{bash} version 1.15
and later.
Dave Love's avatar
Dave Love committed
1261 1262 1263 1264 1265 1266

@node Term Mode
@subsection Term Mode
@cindex Term mode
@cindex mode, Term

1267 1268 1269 1270 1271 1272
  The terminal emulator uses Term mode, which has two input modes.  In
line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
In char mode, each character is sent directly to the inferior
subshell, except for the Term escape character, normally @kbd{C-c}.

  To switch between line and char mode, use these commands:
Dave Love's avatar
Dave Love committed
1273 1274

@table @kbd
1275
@kindex C-c C-j @r{(Term mode)}
Dave Love's avatar
Dave Love committed
1276
@findex term-char-mode
1277
@item C-c C-j
Dave Love's avatar
Dave Love committed
1278 1279
Switch to line mode.  Do nothing if already in line mode.

1280
@kindex C-c C-k @r{(Term mode)}
Dave Love's avatar
Dave Love committed
1281
@findex term-line-mode
1282
@item C-c C-k
Dave Love's avatar
Dave Love committed
1283 1284 1285
Switch to char mode.  Do nothing if already in char mode.
@end table

1286 1287
  The following commands are only available in char mode:

Dave Love's avatar
Dave Love committed
1288 1289 1290 1291
@table @kbd
@item C-c C-c
Send a literal @key{C-c} to the sub-shell.

1292 1293 1294 1295
@item C-c @var{char}
This is equivalent to @kbd{C-x @var{char}} in normal Emacs.  For
example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which
is normally @samp{other-window}.
Dave Love's avatar
Dave Love committed
1296 1297 1298
@end table

@node Paging in Term
1299 1300
@subsection Page-At-A-Time Output
@cindex page-at-a-time
Dave Love's avatar
Dave Love committed
1301

1302 1303
  Term mode has a page-at-a-time feature.  When enabled it makes
output pause at the end of each screenful.
Dave Love's avatar
Dave Love committed
1304 1305 1306 1307 1308

@table @kbd
@kindex C-c C-q @r{(Term mode)}
@findex term-pager-toggle
@item C-c C-q
1309 1310 1311
Toggle the page-at-a-time feature.  This command works in both line
and char modes.  When page-at-a-time is enabled, the mode-line
displays the word @samp{page}.
Dave Love's avatar
Dave Love committed
1312 1313
@end table

1314 1315 1316 1317
  With page-at-a-time enabled, whenever Term receives more than a
screenful of output since your last input, it pauses, displaying
@samp{**MORE**} in the mode-line.  Type @key{SPC} to display the next
screenful of output.  Type @kbd{?} to see your other options.  The
1318
interface is similar to the @code{more} program.
Dave Love's avatar
Dave Love committed
1319

Dave Love's avatar
#  
Dave Love committed
1320 1321 1322 1323 1324 1325 1326
@node Remote Host
@subsection Remote Host Shell
@cindex remote host
@cindex connecting to remote host
@cindex Telnet
@cindex Rlogin

Dave Love's avatar
Dave Love committed
1327 1328 1329 1330
  You can login to a remote computer, using whatever commands you
would from a regular terminal (e.g.@: using the @code{telnet} or
@code{rlogin} commands), from a Term window.

1331 1332 1333 1334 1335 1336
  A program that asks you for a password will normally suppress
echoing of the password, so the password will not show up in the
buffer.  This will happen just as if you were using a real terminal,
if the buffer is in char mode.  If it is in line mode, the password is
temporarily visible, but will be erased when you hit return.  (This
happens automatically; there is no special password processing.)
Dave Love's avatar
Dave Love committed
1337

1338
  When you log in to a different machine, you need to specify the type
1339 1340 1341 1342 1343
of terminal you're using, by setting the @env{TERM} environment
variable in the environment for the remote login command.  (If you use
bash, you do that by writing the variable assignment before the remote
login command, without separating comma.)  Terminal types @samp{ansi}
or @samp{vt100} will work on most systems.
Dave Love's avatar
Dave Love committed
1344 1345

@c   If you are talking to a Bourne-compatible
Gerd Moellmann's avatar
Gerd Moellmann committed
1346
@c shell, and your system understands the @env{TERMCAP} variable,
Dave Love's avatar
Dave Love committed
1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357
@c you can use the command @kbd{M-x shell-send-termcap}, which
@c sends a string specifying the terminal type and size.
@c (This command is also useful after the window has changed size.)

@c You can of course run @samp{gdb} on that remote computer.  One useful
@c trick:  If you invoke gdb with the @code{--fullname} option,
@c it will send special commands to Emacs that will cause Emacs to
@c pop up the source files you're debugging.  This will work
@c whether or not gdb is running on a different computer than Emacs,
@c as long as Emacs can access the source files specified by gdb.

1358
@ignore
1359
  You cannot log in to a remote computer using the Shell mode.
Dave Love's avatar
Dave Love committed
1360 1361
@c (This will change when Shell is re-written to use Term.)
Instead, Emacs provides two commands for logging in to another computer
1362
and communicating with it through an Emacs buffer using Comint mode:
Dave Love's avatar
#  
Dave Love committed
1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400