@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Miscellaneous Commands
various diversions and amusements.
@end iftex
+
+@ifnottex
+@raisesections
+@end ifnottex
+
@node Gnus, Shell, Calendar/Diary, Top
@section Gnus
@cindex Gnus
As opposed to most normal Emacs packages, Gnus uses a number of
different buffers to display information and to receive commands. The
three buffers users spend most of their time in are the @dfn{group
-buffer}, the @dfn{summary buffer} and the @dfn{article buffer}.
+buffer}, the @dfn{summary buffer} and the @dfn{article buffer}.
The @dfn{group buffer} contains a list of groups. This is the first
buffer Gnus displays when it starts up. It normally displays only the
@node Summary of Gnus
@subsection Summary of Gnus Commands
-Reading news is a two step process:
+Reading news is a two-step process:
@enumerate
@item
and display the first unread article in that group.
@need 1000
-In the summary buffer,
+In the summary buffer,
@itemize @bullet
@item
@item
Have Gnus score articles according to various criteria, like author
name, subject, or string in the body of the articles.@*
-@xref{Scoring, , , gnus, The Gnus Manual}.
+@xref{Scoring, , , gnus, The Gnus Manual}.
@item
Send an article to a newsgroup.@*
@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 a shell inside a terminal
+emulator window.
+
+There is a shell implemented entirely in Emacs, documented in a separate
+manual. @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
@table @kbd
@item M-! @var{cmd} @key{RET}
@item M-x shell
Run a subshell with input and output through an Emacs buffer.
You can then give commands interactively.
+@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.
+@item M-x eshell
+@findex eshell
+Start the Emacs shell.
@end table
@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.
+* Shell Prompts:: Two ways to recognize shell prompts.
* History: Shell History. Repeating previous commands in a shell buffer.
+* Directory Tracking:: Keeping track when the subshell changes directory.
* Options: Shell Options. Options for customizing Shell mode.
+* 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.
* Remote Host:: Connecting to another computer.
@end menu
@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
-device. If the shell command produces any output, the output goes into
-an Emacs buffer named @samp{*Shell Command Output*}, which is displayed
-in another window but not selected. A numeric argument, as in @kbd{M-1
-M-!}, directs this command to insert any output into the current buffer.
-In that case, point is left before the output and the mark is set after
-the output.
+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
+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
+instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
+uncompressed equivalent of @file{foo.gz} into the current buffer.
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
-program.
+program. You do not get any status information for an asynchronous
+command, since it hasn't finished yet.
@kindex M-|
@findex shell-command-on-region
first and the output replaces it as the contents of the region. It
returns the command's exit status when it is called from a Lisp program.
+ 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
+@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 it contains.
+
@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.
-To stop waiting, type @kbd{C-g} to quit; that terminates the shell
+ Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete,
+unless you end the command with @samp{&} to make it asynchronous. To
+stop waiting, type @kbd{C-g} to quit; that terminates the shell
command with the signal @code{SIGINT}---the same signal that @kbd{C-c}
-normally generates in the shell. Emacs waits until the command 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.
+normally generates in the shell. Emacs waits until the command
+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.
To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command
-@kbd{C-x @key{RET} c} immediately beforehand. @xref{Specify Coding}.
+@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}.
@vindex shell-command-default-error-buffer
Error output from the command is normally intermixed with the regular
process it; this happens whenever Emacs is waiting for keyboard input or
for time to elapse.
- To make multiple subshells, rename the buffer @samp{*shell*} to
-something different using @kbd{M-x rename-uniquely}. Then type @kbd{M-x
-shell} again to create a new buffer @samp{*shell*} with its own
-subshell. If you rename this buffer as well, you can create a third
-one, and so on. All the subshells run independently and in parallel.
+@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}.
+
+ 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
+create a new @samp{*shell*} buffer using plain @kbd{M-x shell}. All the
+subshells in different buffers run independently and in parallel.
@vindex explicit-shell-file-name
-@cindex @code{ESHELL} environment variable
-@cindex @code{SHELL} environment variable
+@cindex environment variables for subshells
+@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.
+ 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
+@file{~/.emacs_bash}.
+
To specify a coding system for the shell, you can use the command
@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can also
specify a coding system after starting the shell by using @kbd{C-x
-@key{RET} p} in the shell buffer. @xref{Specify Coding}.
-
- As soon as the subshell is started, it is sent as input the contents
-of the file @file{~/.emacs_@var{shellname}}, if that file 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
-@file{~/.emacs_bash}.
-
-@vindex shell-pushd-regexp
-@vindex shell-popd-regexp
-@vindex shell-cd-regexp
- @code{cd}, @code{pushd} and @code{popd} commands given to the inferior
-shell are watched by Emacs so it can keep the @samp{*shell*} buffer's
-default directory the same as the shell's working directory. These
-commands are recognized syntactically by examining lines of input that are
-sent. 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.@refill
-
-@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}).
+@key{RET} p} in the shell buffer. @xref{Communication Coding}.
-@findex dirs
- If Emacs does not properly track 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
-alternative and more aggressive method of tracking changes in the
-current directory.
-
- Emacs defines the environment variable @code{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.
+@cindex @env{EMACS} environment variable
+ Unless the environment variable @env{EMACS} is already defined,
+Emacs defines it 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.
@node Shell Mode
@subsection Shell Mode
@item @key{RET}
@kindex RET @r{(Shell mode)}
@findex comint-send-input
-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.
+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 prompt at the beginning of the line (text output by
+programs preceding your input) is omitted. @xref{Shell Prompts}, for
+how Shell mode recognizes prompts.
@item @key{TAB}
@kindex TAB @r{(Shell mode)}
@vindex shell-completion-fignore
@vindex comint-completion-fignore
The variable @code{shell-completion-fignore} specifies a list of file
-name extensions to ignore in Shell mode completion. The default setting
-ignores file names ending in @samp{~}, @samp{#} or @samp{%}. Other
+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
related Comint modes use the variable @code{comint-completion-fignore}
instead.
@item C-d
@kindex C-d @r{(Shell mode)}
@findex comint-delchar-or-maybe-eof
-Either delete a character or send @sc{EOF}
+Either delete a character or send @acronym{EOF}
(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell
-buffer, @kbd{C-d} sends @sc{EOF} to the subshell. Typed at any other
+buffer, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other
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)}
-@findex comint-bol
+@findex comint-bol-or-process-mark
Move to the beginning of the line, but after the prompt if any
-(@code{comint-bol}). 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.)
+(@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.)
@item C-c @key{SPC}
Accumulate multiple lines of input, then send them together. This
@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
-(@code{comint-kill-input}).
+(@code{comint-kill-input}). If point is not at end of buffer,
+this only kills the part of this text that precedes point.
@item C-c C-w
@kindex C-c C-w @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
Move backward across one shell command, but not beyond the current line
(@code{shell-backward-command}).
-@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}).
-
@item M-x dirs
Ask the shell what its current directory is, so that Emacs can agree
with the shell.
echoing. This is useful when a shell command runs a program that asks
for a password.
-Alternatively, you can arrange for Emacs to notice password prompts
-and turn off echoing for them, as follows:
+Please note that Emacs will not echo passwords by default. If you
+really want them to be echoed, evaluate the following Lisp
+expression:
@example
-(add-hook 'comint-output-filter-functions
- 'comint-watch-for-password-prompt)
+(remove-hook 'comint-output-filter-functions
+ 'comint-watch-for-password-prompt)
@end example
@item M-x comint-continue-subjob
@end example
@end table
- Shell mode also customizes the paragraph commands so that only shell
-prompts start new paragraphs. Thus, a paragraph consists of an input
-command plus the output that follows it in the buffer.
-
@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
-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}).
in a subprocess using unmodified Comint mode---without the
specializations of Shell mode.
+@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}.
+
@node Shell History
@subsection Shell Command History
Shell buffers support three ways of repeating earlier commands. You
-can use the same keys used in the minibuffer; 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.
+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.
@menu
* Ring: Shell Ring. Fetching commands from the history list.
@findex comint-previous-input
@kindex M-p @r{(Shell mode)}
@item M-p
+@itemx C-@key{UP}
Fetch the next earlier old shell command.
@kindex M-n @r{(Shell mode)}
@findex comint-next-input
@item M-n
+@itemx C-@key{DOWN}
Fetch the next later old shell command.
@kindex M-r @r{(Shell mode)}
@itemx M-s @var{regexp} @key{RET}
Search backwards or forwards for old shell commands that match @var{regexp}.
-@item C-c C-x @r{(Shell mode)}
+@item C-c C-x
+@kindex C-c C-x @r{(Shell mode)}
@findex comint-get-next-from-history
Fetch the next subsequent command from the history.
+
+@item C-c .
+@kindex C-c . @r{(Shell mode)}
+@findex comint-input-previous-argument
+Fetch one argument from an old shell command.
+
+@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}).
@end table
Shell buffers provide a history of previously entered shell commands. To
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.
- @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{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}.
The history search commands @kbd{M-r} and @kbd{M-s} read a regular
expression and search through the history for a matching command. Aside
from the choice of which command to fetch, they work just like @kbd{M-p}
-and @kbd{M-r}. If you enter an empty regexp, these commands reuse the
+and @kbd{M-n}. If you enter an empty regexp, these commands reuse the
same regexp used last time.
When you find the previous input you want, you can resubmit it by
can reexecute several successive commands by typing @kbd{C-c C-x
@key{RET}} over and over.
+ 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).
+
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
@vindex shell-input-ring-file-name
Some shells store their command histories in files so that you can
-refer to previous commands from previous shell sessions. Emacs reads
+refer to commands from previous shell sessions. Emacs reads
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.
Move point to the following prompt (@code{comint-next-prompt}).
@kindex C-c RET @r{(Shell mode)}
-@findex comint-copy-old-input
+@findex comint-insert-input
@item C-c @key{RET}
Copy the input command which point is in, inserting the copy at the end
-of the buffer (@code{comint-copy-old-input}). This is useful if you
+of the buffer (@code{comint-insert-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.
+
+@item Mouse-2
+Copy the input command that you click on, inserting the copy at the end
+of the buffer.
@end table
Moving to a previous input and then copying it with @kbd{C-c
-@key{RET}} 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.
+@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.
@node History References
@subsubsection Shell History References
@cindex history reference
- Various shells including csh and bash support @dfn{history references}
-that begin with @samp{!} and @samp{^}. Shell mode can understand these
-constructs and 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}.
+ 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.
-@vindex shell-prompt-pattern
-@vindex comint-prompt-regexp
- History references take effect only following a shell prompt. 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}.
+ 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
- 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}.
-
@findex comint-magic-space
- You can make @key{SPC} perform history expansion by binding @key{SPC} to
-the command @code{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}.
+
+ Shell mode recognizes history references when they follow a prompt.
+@xref{Shell Prompts}, for how Shell mode recognizes prompts.
+
+@node Directory Tracking
+@subsection Directory Tracking
+@cindex directory tracking
+
+@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.
+
+ 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.
+
+@ignore @c This seems to have been deleted long ago.
+@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}).
+@end ignore
+
+@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
+alternative and more aggressive method of tracking changes in the
+current directory.
@node Shell Options
@subsection Shell Mode Options
@vindex comint-scroll-show-maximum-output
If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then
-scrolling due to arrival of output tries to place the last line of text
-at the bottom line of the window, so as to show as much useful text as
-possible. (This mimics the scrolling behavior of many terminals.)
-The default is @code{nil}.
+arrival of output when point is at the end tries to place the last line of
+text at the bottom line of the window, so as to show as much useful
+text as possible. (This mimics the scrolling behavior of many
+terminals.) The default is @code{nil}.
-@vindex comint-scroll-to-bottom-on-output
- By setting @code{comint-scroll-to-bottom-on-output}, you can opt for
+@vindex comint-move-point-for-output
+ By setting @code{comint-move-point-for-output}, you can opt for
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
-@code{all}, point jumps in each window that shows the comint buffer. If
+@code{all}, point jumps in each window that shows the Comint buffer. If
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.
+@vindex comint-prompt-read-only
+ If you set @code{comint-prompt-read-only}, the prompts in the Comint
+buffer are read-only.
+
@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}
@code{comint-completion-autolist}, if non-@code{nil}, says to list all
the possible completions whenever completion is not exact.
-@findex comint-dynamic-complete-variable
- The command @code{comint-dynamic-complete-variable} does variable-name
-completion using the environment variables as set within Emacs. The
-variables controlling file name completion apply to variable-name
-completion too. This command is normally available through the menu
-bar.
-
-@vindex shell-command-execonly
+@vindex shell-completion-execonly
Command completion normally considers only executable files.
-If you set @code{shell-command-execonly} to @code{nil},
+If you set @code{shell-completion-execonly} to @code{nil},
it considers nonexecutable files as well.
@findex shell-pushd-tohome
(@code{shell-pushd-dunique}). The values you choose should match the
underlying shell, of course.
+ If you want Shell mode to handle color output from shell commands,
+you can enable ANSI Color mode. Here is how to do this:
+
+@example
+(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)
+@end example
+
+@node Terminal emulator
+@subsection Emacs Terminal Emulator
+@findex term
+
+ To run a subshell in a terminal emulator, putting its typescript in
+an Emacs buffer, 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.
+
+ 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, 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}).
+Any ``terminal output'' from the subshell goes into the buffer,
+advancing point.
+
+ 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.
+
+ The file name used to load the subshell is determined the same way
+as for Shell mode. To make multiple terminal emulators, rename the
+buffer @samp{*terminal*} to something different using @kbd{M-x
+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.
+
+@node Term Mode
+@subsection Term Mode
+@cindex Term mode
+@cindex mode, Term
+
+ 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:
+
+@table @kbd
+@kindex C-c C-j @r{(Term mode)}
+@findex term-char-mode
+@item C-c C-j
+Switch to line mode. Do nothing if already in line mode.
+
+@kindex C-c C-k @r{(Term mode)}
+@findex term-line-mode
+@item C-c C-k
+Switch to char mode. Do nothing if already in char mode.
+@end table
+
+ The following commands are only available in char mode:
+
+@table @kbd
+@item C-c C-c
+Send a literal @key{C-c} to the sub-shell.
+
+@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}.
+@end table
+
+@node Paging in Term
+@subsection Page-At-A-Time Output
+@cindex page-at-a-time
+
+ Term mode has a page-at-a-time feature. When enabled it makes
+output pause at the end of each screenful.
+
+@table @kbd
+@kindex C-c C-q @r{(Term mode)}
+@findex term-pager-toggle
+@item C-c C-q
+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}.
+@end table
+
+ 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
+interface is similar to the @code{more} program.
+
@node Remote Host
@subsection Remote Host Shell
@cindex remote host
@cindex Telnet
@cindex Rlogin
- Emacs provides two commands for logging in to another computer
-and communicating with it through an Emacs buffer.
+ 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.
+
+ 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.)
+
+ When you log in to a different machine, you need to specify the type
+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.
+
+@c If you are talking to a Bourne-compatible
+@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.)
+
+@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.
+
+@ignore
+ You cannot log in to a remote computer using the Shell mode.
+@c (This will change when Shell is re-written to use Term.)
+Instead, Emacs provides two commands for logging in to another computer
+and communicating with it through an Emacs buffer using Comint mode:
@table @kbd
@item M-x telnet @key{RET} @var{hostname} @key{RET}
argument means use local names, and a negative argument means turn
off directory tracking.
-@node Emacs Server, Hardcopy, Shell, Top
+@end ignore
+
+@node Emacs Server, Printing, Shell, Top
@section Using Emacs as a Server
@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.
+doesn't share the buffers in any existing Emacs process.
You can arrange to use your existing Emacs process as the editor for
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.
- You can switch to a server buffer manually if you wish; you don't have
-to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the only way to
-say that you are ``finished'' with one.
+ You can switch to a server buffer manually if you wish; you don't
+have to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the way to
+say that you are finished with one.
+
+@vindex server-kill-new-buffers
+@vindex server-temp-file-regexp
+ Finishing with a server buffer also kills the buffer, unless it
+already existed in the Emacs session before the server asked to create
+it. However, if you set @code{server-kill-new-buffers} to @code{nil},
+then a different criterion is used: finishing with a server buffer
+kills it if the file name matches the regular expression
+@code{server-temp-file-regexp}. This is set up to distinguish certain
+``temporary'' files.
@vindex server-window
If you set the variable @code{server-window} to a window or a frame,
@kbd{C-x #} displays the server buffer in that window or in that frame.
+@vindex server-name
+ You can run multiple Emacs servers on the same machine by giving
+each one a unique ``server name'', using the variable
+@code{server-name}. For example, @kbd{M-x set-variable @key{RET}
+server-name @key{RET} foo @key{RET}} sets the server name to
+@samp{foo}. The @code{emacsclient} program can visit a server by name
+using the @samp{-s} option. @xref{Invoking emacsclient}.
+
While @code{mail} or another application is waiting for
@code{emacsclient} to finish, @code{emacsclient} does not read terminal
input. So the terminal that @code{mail} was using is effectively
blocked for the duration. In order to edit with your principal Emacs,
you need to be able to use it without using that terminal. There are
-two ways to do this:
+three ways to do this:
@itemize @bullet
@item
switching windows.
@item
-Use Shell mode in Emacs to run the other program such as @code{mail};
-then, @code{emacsclient} blocks only the subshell under Emacs, and you
-can still use Emacs to edit the file.
-@end itemize
+Using virtual terminals, run @code{mail} in one virtual terminal
+and run Emacs in another.
-@vindex server-temp-file-regexp
- Some programs write temporary files for you to edit. After you edit
-the temporary file, the program reads it back and deletes it. If the
-Emacs server is later asked to edit the same file name, it should assume
-this has nothing to do with the previous occasion for that file name.
-The server accomplishes this by killing the temporary file's buffer when
-you finish with the file. Use the variable
-@code{server-temp-file-regexp} to specify which files are temporary in
-this sense; its value should be a regular expression that matches file
-names that are temporary.
+@item
+Use Shell mode or Term mode in Emacs to run the other program such as
+@code{mail}; then, @code{emacsclient} blocks only the subshell under
+Emacs, and you can still use Emacs to edit the file.
+@end itemize
If you run @code{emacsclient} with the option @samp{--no-wait}, it
-returns immediately without waiting for you to ``finish'' the buffer in
-Emacs.
+returns immediately without waiting for you to ``finish'' the buffer
+in Emacs. Note that server buffers created in this way are not killed
+automatically when you finish with them.
@menu
-* Invoking emacsclient::
+* Invoking emacsclient:: Emacs client startup options.
@end menu
@node Invoking emacsclient,, Emacs Server, Emacs Server
-@section Invoking @code{emacsclient}
+@subsection Invoking @code{emacsclient}
To run the @code{emacsclient} program, specify file names as arguments,
and optionally line numbers as well. Do it like this:
@example
-emacsclient @r{@{}@r{[}+@var{line}@r{]} @var{filename}@r{@}}@dots{}
+emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
@end example
+@noindent
This tells Emacs to visit each of the specified files; if you specify a
line number for a certain file, Emacs moves to that line in the file.
+If you specify a column number as well, Emacs puts point on that column
+in the line.
+
+ Ordinarily, @code{emacsclient} does not return until you use the
+@kbd{C-x #} command on each of these buffers. When that happens,
+Emacs sends a message to the @code{emacsclient} program telling it to
+return.
-Ordinarily, @code{emacsclient} does not return until you use the
-@kbd{C-x #} command on each of these buffers. When that happens, Emacs
-sends a message to the @code{emacsclient} program telling it to return.
+ But if you use the option @samp{-n} or @samp{--no-wait} when running
+@code{emacsclient}, then it returns immediately. (You can take as
+long as you like to edit the files in Emacs.)
-But if you use the option @samp{-n} or @samp{--no-wait} when running
-@code{emacsclient}, then it returns immediately. (You can take as long
-as you like to edit the files in Emacs.)
+ The option @samp{--alternate-editor=@var{command}} is useful when
+running @code{emacsclient} in a script. It specifies a command to run
+if @code{emacsclient} fails to contact Emacs. For example, the
+following setting for the @var{EDITOR} environment variable will
+always give you an editor, even if no Emacs server is running:
+@example
+EDITOR="emacsclient --alternate-editor emacs +%d %s"
+@end example
-@node Hardcopy, Postscript, Emacs Server, Top
-@section Hardcopy Output
+@noindent
+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 bash
+function which will communicate with a running Emacs server, or start
+one if none exists.
+
+If you use several displays, you can tell Emacs on which display to
+open the given files with the option @samp{--display=@var{DISPLAY}}.
+This can be used typically when connecting from home to an Emacs
+server running on your machine at your workplace.
+
+If there is more than one Emacs server running, you can specify a
+server name with the option @samp{-s @var{name}}.
+
+You can also use @code{emacsclient} to execute any piece of Emacs Lisp
+code, using the option @samp{--eval}. When this option is given, the
+rest of the arguments is not taken as a list of files to visit but as
+a list of expressions to evaluate.
+
+@node Printing, Sorting, Emacs Server, Top
+@section Printing Hard Copies
@cindex hardcopy
+@cindex printing
- The Emacs commands for making hardcopy let you print either an entire
-buffer or just part of one, either with or without page headers.
-See also the hardcopy commands of Dired (@pxref{Misc File Ops})
-and the diary (@pxref{Diary Commands}).
+ Emacs provides commands for printing hard copies of either an entire
+buffer or just part of one, with or without page headers. You can
+invoke the printing commands directly, as detailed in the following
+section, or using the @samp{File} menu on the menu bar. See also the
+hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary
+(@pxref{Displaying the Diary}).
@table @kbd
@item M-x print-buffer
@code{lpr-add-switches} should be @code{nil} if your printer program is
not compatible with @code{lpr}.
-@node Postscript, Postscript Variables, Hardcopy, Top
-@section Postscript Hardcopy
+@menu
+* PostScript:: Printing buffers or regions as PostScript.
+* PostScript Variables:: Customizing the PostScript printing commands.
+* Printing Package:: An optional advanced printing interface.
+@end menu
- These commands convert buffer contents to Postscript,
+@node PostScript, PostScript Variables,, Printing
+@section PostScript Hardcopy
+
+ These commands convert buffer contents to PostScript,
either printing it or leaving it in another Emacs buffer.
@table @kbd
@item M-x ps-print-buffer
-Print hardcopy of the current buffer in Postscript form.
+Print hardcopy of the current buffer in PostScript form.
@item M-x ps-print-region
-Print hardcopy of the current region in Postscript form.
+Print hardcopy of the current region in PostScript form.
@item M-x ps-print-buffer-with-faces
-Print hardcopy of the current buffer in Postscript form, showing the
-faces used in the text by means of Postscript features.
+Print hardcopy of the current buffer in PostScript form, showing the
+faces used in the text by means of PostScript features.
@item M-x ps-print-region-with-faces
-Print hardcopy of the current region in Postscript form, showing the
+Print hardcopy of the current region in PostScript form, showing the
faces used in the text.
@item M-x ps-spool-buffer
-Generate Postscript for the current buffer text.
+Generate PostScript for the current buffer text.
@item M-x ps-spool-region
-Generate Postscript for the current region.
+Generate PostScript for the current region.
@item M-x ps-spool-buffer-with-faces
-Generate Postscript for the current buffer, showing the faces used.
+Generate PostScript for the current buffer, showing the faces used.
@item M-x ps-spool-region-with-faces
-Generate Postscript for the current region, showing the faces used.
+Generate PostScript for the current region, showing the faces used.
+@item M-x handwrite
+Generates/prints PostScript for the current buffer as if handwritten.
@end table
@findex ps-print-region
@findex ps-print-buffer
@findex ps-print-region-with-faces
@findex ps-print-buffer-with-faces
- The Postscript commands, @code{ps-print-buffer} and
-@code{ps-print-region}, print buffer contents in Postscript form. One
+ The PostScript commands, @code{ps-print-buffer} and
+@code{ps-print-region}, print buffer contents in PostScript form. One
command prints the entire buffer; the other, just the region. The
corresponding @samp{-with-faces} commands,
@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces},
-use Postscript features to show the faces (fonts and colors) in the text
+use PostScript features to show the faces (fonts and colors) in the text
properties of the text being printed.
If you are using a color display, you can print a buffer of program
@findex ps-spool-region-with-faces
@findex ps-spool-buffer-with-faces
The commands whose names have @samp{spool} instead of @samp{print}
-generate the Postscript output in an Emacs buffer instead of sending
+generate the PostScript output in an Emacs buffer instead of sending
it to the printer.
+@findex handwrite
+@cindex handwriting
+@kbd{M-x handwrite} is more frivolous. It generates a PostScript
+rendition of the current buffer as a cursive handwritten document. It
+can be customized in group @code{handwrite}. This function only
+supports ISO 8859-1 characters.
+
@ifinfo
The following section describes variables for customizing these commands.
@end ifinfo
-@node Postscript Variables, Sorting, Postscript, Top
-@section Variables for Postscript Hardcopy
+@node PostScript Variables, Printing Package, PostScript, Printing
+@section Variables for PostScript Hardcopy
@vindex ps-lpr-command
@vindex ps-lpr-switches
@vindex ps-printer-name
- All the Postscript hardcopy commands use the variables
+ All the PostScript hardcopy commands use the variables
@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print
the output. @code{ps-lpr-command} specifies the command name to run,
@code{ps-lpr-switches} specifies command line options to use, and
is @code{nil}, @code{printer-name} is used.
@vindex ps-print-header
-@vindex ps-print-color-p
The variable @code{ps-print-header} controls whether these commands
add header lines to each page---set it to @code{nil} to turn headers
-off. You can turn off color processing by setting
-@code{ps-print-color-p} to @code{nil}.
+off.
+
+@cindex color emulation on black-and-white printers
+@vindex ps-print-color-p
+ If your printer doesn't support colors, you should turn off color
+processing by setting @code{ps-print-color-p} to @code{nil}. By
+default, if the display supports colors, Emacs produces hardcopy output
+with color information; on black-and-white printers, colors are emulated
+with shades of gray. This might produce illegible output, even if your
+screen colors only use shades of gray.
+
+@vindex ps-use-face-background
+ By default, PostScript printing ignores the background colors of the
+faces, unless the variable @code{ps-use-face-background} is
+non-@code{nil}. This is to avoid unwanted interference with the zebra
+stripes and background image/text.
@vindex ps-paper-type
@vindex ps-page-dimensions-database
@code{Times}. The variable @code{ps-font-size} specifies the size of
the font for ordinary text. It defaults to 8.5 points.
- Many other customization variables for these commands are defined and
-described in the Lisp file @file{ps-print.el}.
+@vindex ps-multibyte-buffer
+@cindex Intlfonts for PostScript printing
+@cindex fonts for PostScript printing
+ Emacs supports more scripts and characters than a typical PostScript
+printer. Thus, some of the characters in your buffer might not be
+printable using the fonts built into your printer. You can augment
+the fonts supplied with the printer with those from the GNU Intlfonts
+package, or you can instruct Emacs to use Intlfonts exclusively. The
+variable @code{ps-multibyte-buffer} controls this: the default value,
+@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1
+characters; a value of @code{non-latin-printer} is for printers which
+have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean
+characters built into them. A value of @code{bdf-font} arranges for
+the BDF fonts from the Intlfonts package to be used for @emph{all}
+characters. Finally, a value of @code{bdf-font-except-latin}
+instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1
+characters, and Intlfonts BDF fonts for the rest.
+
+@vindex bdf-directory-list
+ To be able to use the BDF fonts, Emacs needs to know where to find
+them. The variable @code{bdf-directory-list} holds the list of
+directories where Emacs should look for the fonts; the default value
+includes a single directory @file{/usr/local/share/emacs/fonts/bdf}.
-@node Sorting, Narrowing, Postscript Variables, Top
+ Many other customization variables for these commands are defined and
+described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}.
+
+@node Printing Package,, PostScript Variables, Printing
+@section Printing Package
+@cindex Printing package
+
+ The basic Emacs facilities for printing hardcopy can be extended
+using the Printing package. This provides an easy-to-use interface
+for choosing what to print, previewing PostScript files before
+printing, and setting various printing options such as print headers,
+landscape or portrait modes, duplex modes, and so forth. On GNU/Linux
+or Unix systems, the Printing package relies on the @file{gs} and
+@file{gv} utilities, which are distributed as part of the GhostScript
+program. On MS-Windows, the @file{gstools} port of Ghostscript can be
+used.
+
+@findex pr-interface
+ To use the Printing package, add @code{(require 'printing)} to your
+init file (@pxref{Init File}), followed by @code{(pr-update-menus)}.
+This function replaces the usual printing commands in the menu bar
+with a @samp{Printing} submenu that contains various printing options.
+You can also type @kbd{M-x pr-interface RET}; this creates a
+@samp{*Printing Interface*} buffer, similar to a customization buffer,
+where you can set the printing options. After selecting what and how
+to print, you start the print job using the @samp{Print} button (click
+@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For
+further information on the various options, use the @samp{Interface
+Help} button.
+
+@node Sorting, Narrowing, Printing, Top
@section Sorting Text
@cindex sorting
Emacs provides several commands for sorting text in the buffer. All
-operate on the contents of the region (the text between point and the
-mark). They divide the text of the region into many @dfn{sort records},
+operate on the contents of the region.
+They divide the text of the region into many @dfn{sort records},
identify a @dfn{sort key} for each record, and then reorder the records
into the order determined by the sort keys. The records are ordered so
that their keys are in alphabetical order, or, for numeric sorting, in
numeric order. In alphabetic sorting, all upper-case letters `A' through
-`Z' come before lower-case `a', in accord with the ASCII character
+`Z' come before lower-case `a', in accord with the @acronym{ASCII} character
sequence.
The various sort commands differ in how they divide the text into sort
@findex sort-pages
@findex sort-fields
@findex sort-numeric-fields
+@vindex sort-numeric-base
@table @kbd
@item M-x sort-lines
Divide the region into lines, and sort by comparing the entire
field 1, etc. A negative argument means count fields from the right
instead of from the left; thus, minus 1 means sort by the last field.
If several lines have identical contents in the field being sorted, they
-keep same relative order that they had in the original buffer.
+keep the same relative order that they had in the original buffer.
@item M-x sort-numeric-fields
Like @kbd{M-x sort-fields} except the specified field is converted
to an integer for each line, and the numbers are compared. @samp{10}
comes before @samp{2} when considered as text, but after it when
-considered as a number.
+considered as a number. By default, numbers are interpreted according
+to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or
+@samp{0} are interpreted as hexadecimal and octal, respectively.
@item M-x sort-columns
Like @kbd{M-x sort-fields} except that the text within each line
columns by putting point at one of the columns and the mark at the other
column. Because this means you cannot put point or the mark at the
beginning of the first line of the text you want to sort, this command
-uses an unusual definition of `region': all of the line point is in is
+uses an unusual definition of ``region'': all of the line point is in is
considered part of the region, and so is all of the line the mark is in,
as well as all the lines in between.
paragraph by eliminating clutter. It can also be used to restrict the
range of operation of a replace command or repeating keyboard macro.
-@c WideCommands
@table @kbd
@item C-x n n
Narrow down to between point and mark (@code{narrow-to-region}).
@findex narrow-to-region
The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}).
It sets the current buffer's restrictions so that the text in the current
-region remains accessible but all text before the region or after the region
-is inaccessible. Point and mark do not change.
+region remains accessible, but all text before the region or after the
+region is inaccessible. Point and mark do not change.
@kindex C-x n p
@findex narrow-to-page
@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 @code{short}s or @code{int}s, etc.; type @kbd{C-h a
+hexl-@key{RET}} for details.
+
+
@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top
@section Saving Emacs Sessions
@cindex saving sessions
+@cindex restore session
+@cindex remember editing session
+@cindex reload files
@cindex desktop
- You can use the Desktop library to save the state of Emacs from one
-session to another. Saving the state means that Emacs starts up with
-the same set of buffers, major modes, buffer positions, and so on that
-the previous Emacs session had.
+ Use the desktop library to save the state of Emacs from one session
+to another. Once you save the Emacs @dfn{desktop}---the buffers,
+their file names, major modes, buffer positions, and so on---then
+subsequent Emacs sessions reload the saved desktop.
-@vindex desktop-enable
- To use Desktop, you should use the Customization buffer (@pxref{Easy
-Customization}) to set @code{desktop-enable} to a non-@code{nil} value,
-or add these lines at the end of your @file{.emacs} file:
+@findex desktop-save
+@vindex desktop-save-mode
+ You can save the desktop manually with the command @kbd{M-x
+desktop-save}. You can also enable automatic desktop saving when
+you exit Emacs: use the Customization buffer (@pxref{Easy
+Customization}) to set @code{desktop-save-mode} to @code{t} for future
+sessions, or add this line in your @file{~/.emacs} file:
@example
-(desktop-load-default)
-(desktop-read)
+(desktop-save-mode 1)
@end example
-@noindent
-@findex desktop-save
-The first time you save the state of the Emacs session, you must do it
-manually, with the command @kbd{M-x desktop-save}. Once you have done
-that, exiting Emacs will save the state again---not only the present
-Emacs session, but also subsequent sessions. You can also save the
-state at any time, without exiting Emacs, by typing @kbd{M-x
-desktop-save} again.
-
- In order for Emacs to recover the state from a previous session, you
-must start it with the same current directory as you used when you
-started the previous session. This is because @code{desktop-read} looks
-in the current directory for the file to read. This means that you can
-have separate saved sessions in different directories; the directory in
-which you start Emacs will control which saved session to use.
-
-@vindex desktop-files-not-to-save
- The variable @code{desktop-files-not-to-save} controls which files are
-excluded from state saving. Its value is a regular expression that
-matches the files to exclude. By default, remote (ftp-accessed) files
-are excluded; this is because visiting them again in the subsequent
-session would be slow. If you want to include these files in state
-saving, set @code{desktop-files-not-to-save} to @code{"^$"}.
-@xref{Remote Files}.
+@findex desktop-change-dir
+@findex desktop-revert
+ When Emacs starts, it looks for a saved desktop in the current
+directory. Thus, you can have separate saved desktops in different
+directories, and the starting directory determines which one Emacs
+reloads. You can save the current desktop and reload one saved in
+another directory by typing @kbd{M-x desktop-change-dir}. Typing
+@kbd{M-x desktop-revert} reverts to the desktop previously reloaded.
+
+ Specify the option @samp{--no-desktop} on the command line when you
+don't want it to reload any saved desktop. This turns off
+@code{desktop-save-mode} for the current session.
+
+@vindex desktop-restore-eager
+ By default, all the buffers in the desktop are restored at one go.
+However, this may be slow if there are a lot of buffers in the
+desktop. You can specify the maximum number of buffers to restore
+immediately with the variable @code{desktop-restore-eager}; the
+remaining buffers are restored ``lazily,'' when Emacs is idle.
+
+@findex desktop-clear
+@vindex desktop-globals-to-clear
+@vindex desktop-clear-preserve-buffers-regexp
+ Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills
+all buffers except for internal ones, and clears the global variables
+listed in @code{desktop-globals-to-clear}. If you want this to
+preserve certain buffers, customize the variable
+@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular
+expression matching the names of buffers not to kill.
+
+ If you want to save minibuffer history from one session to
+another, use the @code{savehist} library.
@node Recursive Edit, Emulation, Saving Emacs Sessions, Top
@section Recursive Editing Levels
The mode line shows you when you are in a recursive edit by displaying
square brackets around the parentheses that always surround the major and
-minor mode names. Every window's mode line shows this, in the same way,
+minor mode names. Every window's mode line shows this in the same way,
since being in a recursive edit is true of Emacs as a whole rather than
any particular window or buffer.
Mode lines display a pair of square brackets for each recursive editing
level currently in progress.
- Exiting the inner recursive edit (such as, with the debugger @kbd{c}
+ Exiting the inner recursive edit (such as with the debugger @kbd{c}
command) resumes the command running in the next level up. When that
command finishes, you can then use @kbd{C-M-c} to exit another recursive
editing level, and so on. Exiting applies to the innermost level only.
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
@cindex EDT
@cindex vi
+@cindex PC key bindings
+@cindex scrolling all windows
+@cindex PC selection
+@cindex Motif key bindings
+@cindex Macintosh key bindings
+@cindex WordStar
GNU Emacs can be programmed to emulate (more or less) most other
editors. Standard facilities can emulate these:
@table @asis
+@item CRiSP/Brief (PC editor)
+@findex crisp-mode
+@vindex crisp-override-meta-x
+@findex scroll-all-mode
+@cindex CRiSP mode
+@cindex Brief emulation
+@cindex emulation of Brief
+@cindex mode, CRiSP
+You can turn on key bindings to emulate the CRiSP/Brief editor with
+@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs
+unless you set the variable @code{crisp-override-meta-x}. You can
+also use the command @kbd{M-x scroll-all-mode} or set the variable
+@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
@findex edt-emulation-off
are done in the global keymap, so there is no problem switching
buffers or major modes while in EDT emulation.
+@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
not use it.
@inforef{Top, VIP, vip}, for full information.
+
+@item WordStar (old wordprocessor)
+@findex wordstar-mode
+@kbd{M-x wordstar-mode} provides a major mode with WordStar-like
+key bindings.
+@end table
+
+@node Hyperlinking, Dissociated Press, Emulation, Top
+@section Hyperlinking and Navigation Features
+
+@cindex hyperlinking
+@cindex navigation
+ Various modes documented elsewhere have hypertext features so that
+you can follow links, usually by clicking @kbd{Mouse-2} on the link or
+typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1}
+quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer
+if you want to set point instead.)
+
+ Info mode, Help mode and the Dired-like modes are examples of modes
+that have links in the buffer. 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.
+@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.
+
+ The general way to use this feature is to type @kbd{M-x browse-url},
+which displays a specified URL. If point is located near a plausible
+URL, that URL is used as the default. 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 behavior 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} under the @samp{hypermedia} keyword provides more information.
+Packages with facilities for following URLs should always go through
+Browse-URL, so that the customization options for Browse-URL will
+affect all browsing in Emacs.
+
+@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
-@node Dissociated Press, Amusements, Emulation, Top
+ You can make URLs in the current buffer active with @kbd{M-x
+goto-address}. This finds all the URLs in the buffer, and establishes
+bindings for @kbd{Mouse-2} and @kbd{C-c @key{RET}} on them. After
+activation, if you click on a URL with @kbd{Mouse-2}, or move to a URL
+and type @kbd{C-c @key{RET}}, that will display the web page that the URL
+specifies. For a @samp{mailto} URL, it sends mail instead, using your
+selected mail-composition method (@pxref{Mail Methods}).
+
+ It can be useful to add @code{goto-address} to mode hooks and the
+hooks used to display an incoming message.
+@code{rmail-show-message-hook} is the appropriate hook for Rmail, and
+@code{mh-show-mode-hook} for MH-E. This is not needed for Gnus,
+which has a similar feature of its own.
+
+
+@node FFAP
+@subsection Finding Files and URLs at Point
+@findex find-file-at-point
+@findex ffap
+@findex dired-at-point
+@findex ffap-next
+@findex ffap-menu
+@cindex finding file at point
+
+ FFAP mode replaces certain key bindings for finding files, including
+@kbd{C-x C-f}, with commands that provide more sensitive defaults.
+These commands behave like the ordinary ones when given a prefix
+argument. Otherwise, they get the default file name or URL from the
+text around point. If what is found in the buffer has the form of a
+URL rather than a file name, the commands use @code{browse-url} to
+view it.
+
+ This feature is useful for following references in mail or news
+buffers, @file{README} files, @file{MANIFEST} files, and so on. The
+@samp{ffap} package's commentary available via @kbd{C-h p} under the
+@samp{files} keyword and the @code{ffap} Custom group provide details.
+
+@cindex FFAP minor mode
+@findex ffap-mode
+ You can turn on FFAP minor mode by calling @code{ffap-bindings} 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 @var{filename} @key{RET}
+@kindex C-x C-f @r{(FFAP)}
+Find @var{filename}, guessing a default from text around point
+(@code{find-file-at-point}).
+@item C-x C-r
+@kindex C-x C-r @r{(FFAP)}
+@code{ffap-read-only}, analogous to @code{find-file-read-only}.
+@item C-x C-v
+@kindex C-x C-v @r{(FFAP)}
+@code{ffap-alternate-file}, analogous to @code{find-alternate-file}.
+@item C-x d @var{directory} @key{RET}
+@kindex C-x d @r{(FFAP)}
+Start Dired on @var{directory}, defaulting to the directory name at
+point (@code{dired-at-point}).
+@item C-x C-d
+@code{ffap-list-directory}, analogous to @code{list-directory}.
+@item C-x 4 f
+@kindex C-x 4 f @r{(FFAP)}
+@code{ffap-other-window}, analogous to @code{find-file-other-window}.
+@item C-x 4 r
+@code{ffap-read-only-other-window}, analogous to
+@code{find-file-read-only-other-window}.
+@item C-x 4 d
+@code{ffap-dired-other-window}, analogous to @code{dired-other-window}.
+@item C-x 5 f
+@kindex C-x 5 f @r{(FFAP)}
+@code{ffap-other-frame}, analogous to @code{find-file-other-frame}.
+@item C-x 5 r
+@code{ffap-read-only-other-frame}, analogous to
+@code{find-file-read-only-other-frame}.
+@item C-x 5 d
+@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}.
+@item M-x ffap-next
+Search buffer for next file name or URL, then find that file or URL.
+@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)}
+Display a menu of files and URLs mentioned in current buffer, then
+find the one you select (@code{ffap-menu}).
+@end table
+
+@node Dissociated Press, Amusements, Hyperlinking, Top
@section Dissociated Press
@findex dissociated-press
buffer to another. In order to produce plausible output rather than
gibberish, it insists on a certain amount of overlap between the end of
one run of consecutive words or characters and the start of the next.
-That is, if it has just printed out `president' and then decides to jump
+That is, if it has just output `president' and then decides to jump
to a different point in the file, it might spot the `ent' in `pentagon'
and continue from there, producing `presidentagon'.@footnote{This
dissociword actually appeared during the Vietnam War, when it was very
@findex hanoi
@findex yow
@findex gomoku
-@findex mpuz
@cindex tower of Hanoi
If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are
-considerably bored, give it a numeric argument. If you are very very
+considerably bored, give it a numeric argument. If you are very, very
bored, try an argument of 9. Sit back and watch.
@cindex Go Moku
@findex blackbox
@findex mpuz
+@findex 5x5
@cindex puzzles
- @kbd{M-x blackbox} and @kbd{M-x mpuz} are two kinds of puzzles.
+ @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are kinds of puzzles.
@code{blackbox} challenges you to determine the location of objects
inside a box by tomography. @code{mpuz} displays a multiplication
puzzle with letters standing for digits in a code that you must
guess---to guess a value, type a letter and then the digit you think it
-stands for.
+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.
+@findex lm
+@cindex landmark game
+@kbd{M-x lm} runs a relatively non-participatory game in which a robot
+attempts to maneuver towards a tree at the center of the window based on
+unique olfactory cues from each of the four directions.
+
+@findex life
+@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 a Pong-like game, 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, producing
+text like this:
+
+@example
+M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region.
+@end example
+
+@findex tetris
+@cindex Tetris
+@findex snake
+@cindex Snake
+@kbd{M-x tetris} runs an implementation of the well-known Tetris game.
+Likewise, @kbd{M-x snake} provides an implementation of Snake.
+
When you are frustrated, try the famous Eliza program. Just do
@kbd{M-x doctor}. End each input by typing @key{RET} twice.
@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.
+
+@ifnottex
+@lowersections
+@end ifnottex
+
+@ignore
+ arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474
+@end ignore