@cindex shell commands
Emacs has commands for passing single command lines to inferior shell
-processes; it can also run a shell interactively with input and output to
-an Emacs buffer named @samp{*shell*}.
+processes; it can also run a shell interactively with input and output
+to an Emacs buffer named @samp{*shell*} or run s shell inside a terminal
+emulator window.
+
+There is a shell implemented entirely in Emacs, documented in a separate
+manual. @xref{, ,Eshell , eshell, Eshell: The Emacs Shell}.
@table @kbd
@item M-! @var{cmd} @key{RET}
Run a subshell with input and output through an Emacs buffer.
You can then give commands interactively.
Full terminal emulation is available.
+@item M-x eshell
+@findex eshell
+Start the Emacs shell.
@end table
@menu
@vindex shell-file-name
@cindex environment
Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the
-shell to use. This variable is initialized based on your @code{SHELL}
+shell to use. This variable is initialized based on your @env{SHELL}
environment variable when Emacs is started. If the file name does not
specify a directory, the directories in the list @code{exec-path} are
searched; this list is initialized based on the environment variable
-@code{PATH} when Emacs is started. Your @file{.emacs} file can override
+@env{PATH} when Emacs is started. Your @file{.emacs} file can override
either or both of these default initializations.@refill
Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete.
one, and so on. All the subshells run independently and in parallel.
@vindex explicit-shell-file-name
-@cindex @code{ESHELL} environment variable
-@cindex @code{SHELL} environment variable
+@cindex @env{ESHELL} environment variable
+@cindex @env{SHELL} environment variable
The file name used to load the subshell is the value of the variable
@code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise,
-the environment variable @code{ESHELL} is used, or the environment
-variable @code{SHELL} if there is no @code{ESHELL}. If the file name
+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
-@code{PATH} when Emacs is started. Your @file{.emacs} file can override
+@env{PATH} when Emacs is started. Your @file{.emacs} file can override
either or both of these default initializations.
To specify a coding system for the shell, you can use the command
alternative and more aggressive method of tracking changes in the
current directory.
- Emacs defines the environment variable @code{EMACS} in the subshell,
+ Emacs defines the environment variable @env{EMACS} in the subshell,
with value @code{t}. A shell script can check this variable to
determine whether it has been run from an Emacs subshell.
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
+@vindex comint-use-prompt-regexp-instead-of-fields
+@cindex prompt, shell
At end of buffer send line as input; otherwise, copy current line to end
of buffer and send it (@code{comint-send-input}). When a line is
-copied, any text at the beginning of the line that matches the variable
-@code{shell-prompt-pattern} is left out; this variable's value should be
-a regexp string that matches the prompts that your shell uses.
+copied, any prompt is left out (where the prompt is the part of the line
+that was not input by the user; see also
+@code{comint-use-prompt-regexp-instead-of-fields}).
@item @key{TAB}
@kindex TAB @r{(Shell mode)}
@item C-c C-o
@kindex C-c C-o @r{(Shell mode)}
-@findex comint-kill-output
-Kill the last batch of output from a shell command
-(@code{comint-kill-output}). This is useful if a shell command spews
-out lots of output that just gets in the way.
+@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.
@item C-c C-r
@itemx C-M-l
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
-command names listed above. The special features of Shell mode in
-particular include the choice of regular expression for detecting
-prompts, the directory tracking feature, and a few user commands.
+command names listed above. The special features of Shell mode include
+the directory tracking feature, and a few user commands.
Other Emacs features that use variants of Comint mode include GUD
(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}).
@vindex shell-prompt-pattern
@vindex comint-prompt-regexp
+@vindex comint-use-prompt-regexp-instead-of-fields
+@cindex prompt, shell
History references take effect only following a shell prompt. The
+prompt is defined to be any text not input by the user, unless the
+variable @code{comint-use-prompt-regexp-instead-of-fields} is
+non-@code{nil} (the default value is @code{nil}). When
+@code{comint-use-prompt-regexp-instead-of-fields} is non-@code{nil}, the
variable @code{shell-prompt-pattern} specifies how to recognize a shell
-prompt. Comint modes in general use the variable
-@code{comint-prompt-regexp} to specify how to find a prompt; Shell mode
-uses @code{shell-prompt-pattern} to set up the local value of
-@code{comint-prompt-regexp}.
+prompt, and comint modes in general use the variable
+@code{comint-prompt-regexp} (shell mode uses @code{shell-prompt-pattern}
+to set up the local value of @code{comint-prompt-regexp}).
@vindex comint-input-autoexpand
Shell mode can optionally expand history references in the buffer when
or @samp{vt100} will work on most systems.
@c If you are talking to a Bourne-compatible
-@c shell, and your system understands the @code{TERMCAP} variable,
+@c shell, and your system understands the @env{TERMCAP} variable,
@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.)
@pindex emacsclient
@cindex Emacs as a server
@cindex server, using Emacs as
-@cindex @code{EDITOR} environment variable
+@cindex @env{EDITOR} environment variable
Various programs such as @code{mail} can invoke your choice of editor
to edit a particular piece of text, such as a message that you are
sending. By convention, most of these programs use the environment
-variable @code{EDITOR} to specify which editor to run. If you set
-@code{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
+variable @env{EDITOR} to specify which editor to run. If you set
+@env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
inconvenient fashion, by starting a new, separate Emacs process. This
is inconvenient because it takes time and because the new Emacs process
doesn't share the buffers in the existing Emacs process.
programs like @code{mail} by using the Emacs client and Emacs server
programs. Here is how.
-@cindex @code{TEXEDIT} environment variable
+@cindex @env{TEXEDIT} environment variable
First, the preparation. Within Emacs, call the function
@code{server-start}. (Your @file{.emacs} file can do this automatically
if you add the expression @code{(server-start)} to it.) Then, outside
-Emacs, set the @code{EDITOR} environment variable to @samp{emacsclient}.
+Emacs, set the @env{EDITOR} environment variable to @samp{emacsclient}.
(Note that some programs use a different environment variable; for
example, to make @TeX{} use @samp{emacsclient}, you should set the
-@code{TEXEDIT} environment variable to @samp{emacsclient +%d %s}.)
+@env{TEXEDIT} environment variable to @samp{emacsclient +%d %s}.)
@kindex C-x #
@findex server-edit
- Then, whenever any program invokes your specified @code{EDITOR}
+ Then, whenever any program invokes your specified @env{EDITOR}
program, the effect is to send a message to your principal Emacs telling
it to visit a file. (That's what the program @code{emacsclient} does.)
Emacs displays the buffer immediately and you can immediately begin
When you've finished editing that buffer, type @kbd{C-x #}
(@code{server-edit}). This saves the file and sends a message back to
the @code{emacsclient} program telling it to exit. The programs that
-use @code{EDITOR} wait for the ``editor'' (actually, @code{emacsclient})
+use @env{EDITOR} wait for the ``editor'' (actually, @code{emacsclient})
to exit. @kbd{C-x #} also checks for other pending external requests
to edit various files, and selects the next such file.
this sense; its value should be a regular expression that matches file
names that are temporary.
+@vindex server-kill-new-buffers
+ If the variable @code{server-kill-new-buffers} is set to non-nil,
+buffers which still have a client are killed when you are done with
+them, unless they were already present before Emacs Server visited
+them. This overrides the effect of the @code{server-temp-file-regexp}
+variable. By default, @code{server-kill-new-buffers} has a non-nil
+value; set it to nil if you want the old behavior governed by
+@code{server-temp-file-regexp}.
+
If you run @code{emacsclient} with the option @samp{--no-wait}, it
returns immediately without waiting for you to ``finish'' the buffer in
-Emacs.
+Emacs. Note that it this case, buffers for temporary files will not be
+killed automatically with the default value of
+@code{server-kill-new-buffers}, since those buffers will not have a
+client.
If you have forgotten to start Emacs, then the option
@samp{--alternate-editor=@var{command}} may be useful. It specifies a
The environment variable @var{ALTERNATE_EDITOR} has the same effect, but
the value of the @samp{--alternate-editor} takes precedence.
+@pindex emacs.bash
+Alternatively, the file @file{etc/emacs.bash} defines a function for
+@command{bash} which will use a running Emacs server or start one if
+none exists.
+
@menu
* Invoking emacsclient::
@end menu
@cindex Hexl mode
@cindex mode, Hexl
@cindex editing binary files
+@cindex hex editing
There is a special major mode for editing binary files: Hexl mode. To
use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit
the file. This command converts the file's contents to hexadecimal and
invoked @code{hexl-mode}.
@end table
+@noindent
+Other Hexl commands let you insert strings (sequences) of binary bytes,
+move by short's or int's, etc.; type @kbd{C-h a hexl- RET} for details.
+
+
@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top
@section Saving Emacs Sessions
@cindex saving sessions
saving, set @code{desktop-files-not-to-save} to @code{"^$"}.
@xref{Remote Files}.
+@vindex save-place
+@cindex Saveplace
+@findex toggle-save-place
+There is a simpler mechanism provided by Saveplace library which records
+your position in each file when you kill its buffer (or kill Emacs), and
+jumps to the same position when you visit the file again (even in
+another Emacs session). Use @kbd{M-x toggle-save-place} to turn on
+place-saving in a given file. Customize the option @code{save-place} to
+turn it on for all files in each session.
+
@node Recursive Edit, Emulation, Saving Emacs Sessions, Top
@section Recursive Editing Levels
@cindex recursive editing level
approaches give you more flexibility to go back to unfinished tasks in
the order you choose.
-@node Emulation, Dissociated Press, Recursive Edit, Top
+@node Emulation, Hyperlinking, Recursive Edit, Top
@section Emulation
@cindex emulating other editors
@cindex other editors
@findex crisp-mode
@vindex crisp-override-meta-x
@findex scroll-all-mode
-Turn on keybindings to emulate the CRiSP/Brief editor with @kbd{M-x
-crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs unless you
-change the user option @code{crisp-override-meta-x}. You can also load
-the @code{scroll-all} package to emulate CRiSP's scroll-all feature
-(scrolling all windows together). Do this either with @kbd{M-x
-scroll-all-mode} or set the user option @code{crisp-load-scroll-all} to
-load it along with @code{crisp-mode}.
+@cindex CRiSP mode
+@cindex Brief emulation
+@cindex mode, CRiSP
+You can turn on keybindings to emulate the CRiSP/Brief editor with
+@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs
+unless you change the user option @code{crisp-override-meta-x}. You can
+also use the command @kbd{M-x scroll-all-mode} or set the user option
+@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature
+(scrolling all windows together).
@item EDT (DEC VMS editor)
@findex edt-emulation-on
@item `PC' bindings
@findex pc-bindings-mode
-@kbd{M-x pc-bindings-mode} sets up certain key bindings for `PC
-compatibility'---what people are often used to on PCs---as follows:
+@cindex `PC' key bindings
+The command @kbd{M-x pc-bindings-mode} sets up certain key bindings for
+`PC compatibility'---what people are often used to on PCs---as follows:
@kbd{Delete} and its variants) delete forward instead of backward,
@kbd{C-Backspace} kills backward a word (as @kbd{C-Delete} normally
would), @kbd{M-Backspace} does undo, @kbd{Home} and @kbd{End} move to
beginning and end of line, @kbd{C-Home} and @kbd{C-End} move to
beginning and end of buffer and @kbd{C-Escape} does @code{list-buffers}.
-@item PC selection mode
+@item PC Selection mode
@findex pc-selection-mode
-@kbd{M-x pc-selction-mode} emulates the mark, copy, cut and paste
+@cindex PC Selection minor mode
+@cindex mode, PC selection
+@cindex selection, `PC'
+The command @kbd{M-x pc-selction-mode} turns on a global minor mode
+which emulates the mark, copy, cut and paste
look-and-feel of Motif programs (which is the same as the Macintosh GUI
and MS-Windows). It makes the keybindings of PC mode and also modifies
the bindings of the cursor keys and the @kbd{next}, @kbd{prior},
operate on the active region, bound to @kbd{C-insert}, @kbd{S-delete}
and @kbd{S-insert} respectively.
+@cindex s-region package
The @code{s-region} package provides similar, but less complete,
facilities.
+@item TPU (DEC VMS editor)
+@findex tpu-edt-on
+@cindex TPU
+@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT.
+
@item vi (Berkeley editor)
@findex viper-mode
Viper is the newest emulator for vi. It implements several levels of
keybindings.
@end table
-@node Dissociated Press, Amusements, Emulation, Top
+@node Hyperlinking, Dissociated Press, Emulation, Top
+@section Hyperlinking and Navigation Features
+
+@cindex hyperlinking
+@cindex URLs
+@cindex navigation
+Various modes documented elsewhere have hypertext features whereby you
+can follow links, usually with @kbd{mouse-2} or @kbd{RET} on the text of
+the link. Info mode, Help mode and the Dired-like modes are examples.
+The Tags facility links between uses and definitions in source files,
+see @ref{Tags}. Imenu provides navigation amongst items indexed in the
+current buffer, see @ref{Imenu}. Info-lookup provides mode-specific
+lookup of definitions in Info indexes, see @ref{Documentation}.
+Speedbar maintains a frame in which links to files, and locations in
+files are displayed, see @ref{Speedbar}.
+
+Other non-mode-specific facilities described in this section enable
+following links from the current buffer in a context-sensitive fashion.
+
+@menu
+* Browse-URL:: Following URLs.
+* Goto-address:: Activating URLs.
+* FFAP:: Finding files etc. at point.
+* Find-func:: Finding function and variable definitions.
+@end menu
+
+@node Browse-URL
+@subsection Following URLs
+@cindex World Wide Web
+@cindex Web
+@findex browse-url
+@findex browse-url-at-point
+@findex browse-url-at-mouse
+@cindex Browse-URL
+@cindex URLs
+
+@table @kbd
+@item M-x browse-url @key{RET} @var{url} @key{ret}
+Load a URL into a Web browser.
+@end table
+
+The Browse-URL package provides facilities for following URLs specifying
+links on the World Wide Web. Usually this works by invoking a web
+browser but you can, for instance, arrange to invoke @code{compose-mail}
+from @samp{mailto:} URLs. Packages such as Gnus may make active links
+from URLs themselves. Otherwise you can use @kbd{M-x browse-url} to
+follow a link, defaulting to the URL at point. Other commands are
+available which you might like to bind to keys, such as
+@code{browse-url-at-point} and @code{browse-url-at-mouse}.
+
+@vindex browse-url-browser-function
+You can customize Browse-URL's behaviour via various options in the
+@code{browse-url} Customize group, particularly
+@code{browse-url-browser-function}. You can invoke actions dependent on
+the type of URL by defining @code{browse-url-browser-function} as an
+association list. The package's commentary available via @kbd{C-h p}
+provides more information. Packages with facilities for following URLs
+should use Browse-URL, so customizing options in the @code{browse-url}
+group should be sufficient to determine how they all work in that
+respect.
+
+@node Goto-address
+@subsection Activating URLs
+@findex goto-address
+@cindex Goto-address
+@cindex URLs, activating
+
+@table @kbd
+@item M-x goto-address
+Activate URLs and e-mail addresses in the current buffer.
+@end table
+
+You can arrange to activate URLs in any buffer with @kbd{M-x
+goto-address}. It may be useful to add @code{goto-address} to hooks
+invoked when buffers are displayed in particular modes.
+@code{rmail-show-message-hook} is the appropriate hook if you use Rmail,
+or @code{mh-show-mode-hook} if you use MH.
+
+@node FFAP
+@subsection Finding Files and URLs at Point
+@findex ffap
+@findex find-file-at-point
+@findex ffap
+@findex ffap-dired-at-point
+@findex ffap-next
+@findex ffap-menu
+@cindex FFAP
+@cindex URLs
+@cindex finding file at point
+
+@table @kbd
+@item M-x ffap @key{RET} @var{filename} @key{RET}
+Find @var{filename}, guessing a default from text around point.
+@item M-x ffap-next
+Search buffer for next file or URL, and run `ffap'. With single prefix
+arg, search backwards, with double arg wrap search forwards, with triple
+arg wrap search backwards.
+@item M-x ffap-menu
+Put up a menu of files and URLs mentioned in current buffer and try to
+fetch the selected one.
+@item M-x ffap-dired-at-point
+Start Dired, defaulting to file at point.
+@end table
+
+The command @kbd{M-x find-file-at-point} (or @kbd{M-x ffap}) can be used
+as a replacement for @kbd{M-x find-file}. With a prefix argument it
+behaves as @kbd{M-x find-file}. Otherwise it tries to guess a default
+file or URL from the text around point. In the case of a URL, it will
+invoke @code{browse-url} rather than finding a file. This is useful for
+following references in mail or news buffers, @file{README}s,
+@file{MANIFEST}s, and so on. The @samp{ffap} package's
+commentary available via @kbd{C-h p} and the @code{ffap} Custom group
+provide details.
+
+@cindex FFAP minor mode
+@findex ffap-mode
+You can turn on FFAP minor mode to make the following key bindings and
+to install hooks for using @code{ffap} in Rmail, Gnus and VM article
+buffers.
+
+@table @kbd
+@item C-x C-f
+@kindex C-x C-f @r{(FFAP)}
+@kbd{find-file-at-point};
+@item C-x 4 f
+@kindex C-x 4 f @r{(FFAP)}
+@code{ffap-other-window}, analagous to @kbd{M-x find-file-other-window};
+@item C-x 5 f
+@kindex C-x 5 f @r{(FFAP)}
+@code{ffap-other-frame}, analagous to @kbd{M-x find-file-other-frame};
+@item C-x d
+@kindex C-x d @r{(FFAP)}
+@code{ffap-dired-at-point}, analogous to @kbd{M-x dired};
+@item S-mouse-3
+@kindex S-mouse-3 @r{(FFAP)}
+@code{ffap-at-mouse} finds the file guessed from text around the position
+of a mouse click;
+@item C-S-mouse-3
+@kindex C-S-mouse-3 @r{(FFAP)}
+@code{ffap-menu} puts up a selectable menu of files and URLs mentioned in
+the current buffer.
+@end table
+
+@node Find-func
+@subsection Finding Function and Variable Definitions
+@findex find-function
+@findex find-function-on-key
+@findex find-variable
+@cindex examples of Lisp functions
+@cindex Lisp examples
+@cindex Find-func
+@cindex Lisp definitions
+@cindex definitions, locating in sources
+@cindex tags
+
+@table @kbd
+@item M-x find-function @key{RET} @var{function} @key{RET}
+Find the definition of the @var{function} at point.
+@item M-x find-variable @key{RET} @var{variable} @key{RET}
+Find the definition of the @var{variable} at point.
+@item M-x find-function-on-key @var{key}
+Find the definition of the function that @var{key} invokes.
+@end table
+
+The Find-func package provides convenient facilities for finding the
+definitions of Emacs Lisp functions and variables. It has a somewhat
+similar function to the Tags facility (@pxref{Tags}) but uses Emacs's
+introspective facilities which maintain information about loaded
+libraries. In contrast to Tags, it only works for functions and
+variables with definitions which are already loaded but it relates to
+the code actually running and doesn't require maintaining tags files.
+
+You need to have the Lisp source (@samp{.el}) files available on your
+load path along with the compiled (@samp{.elc}) versions for this to
+work. You can use compressed source files if you turn on
+@code{auto-compression-mode}.
+
+The commands available include @kbd{M-x find-function} to find the
+definition of a named function, @kbd{find-function-on-key} to find the
+definition of the function bound to a key and @kbd{find-variable} to
+find a variable's definition. These only work for things defined in
+Lisp source files, not primitive functions or variables defined
+primitively in the Emacs layer implemented in C.
+
+Find-func is useful for finding examples of how to do things if you want
+to write an Emacs Lisp extension similar to some existing function.
+
+@node Dissociated Press, Amusements, Hyperlinking, Top
@section Dissociated Press
@findex dissociated-press
guess---to guess a value, type a letter and then the digit you think it
stands for. The aim of @code{5x5} is to fill in all the squares.
+@findex decipher
+@cindex ciphers
+@cindex cryptanalysis
+@kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted
+in a simple monoalphabetic substitution cipher.
+
@findex dunnet
@kbd{M-x dunnet} runs an adventure-style exploration game, which is
a bigger sort of puzzle.
@cindex Life
@kbd{M-x life} runs Conway's `Life' cellular automaton.
+@findex morse-region
+@findex unmorse-region
+@cindex Morse code
+@cindex --/---/.-./.../.
+@kbd{M-x morse-region} converts text in a region to Morse code and
+@kbd{M-x unmorse-region} converts it back. No cause for remorse.
+
+@findex pong
+@cindex Pong game
+@kbd{M-x pong} plays an implementation of the game Pong, bouncing the
+ball off opposing bats.
+
@findex solitaire
@cindex solitaire
@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs
across other pegs.
+@findex studlify-region
+@cindex StudlyCaps
+@kbd{M-x studlify-region} studlify-cases the region, that is
+
+@example
+M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region.
+@end example
+
@findex tetris
@cindex Tetris
@kbd{M-x tetris} runs an implementation of the well-known Tetris game.
@cindex Zippy
When you are feeling strange, type @kbd{M-x yow}.
+
+@findex zone
+The command @kbd{M-x zone} plays games with the display when Emacs is
+idle.