Mercurial > emacs
changeset 84257:d72597c514e0
Move here from ../../man
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:47:39 +0000 |
| parents | a0ed20459197 |
| children | b8ab739ca1b8 |
| files | doc/emacs/misc.texi |
| diffstat | 1 files changed, 2559 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/emacs/misc.texi Thu Sep 06 04:47:39 2007 +0000 @@ -0,0 +1,2559 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@iftex +@chapter Miscellaneous Commands + + This chapter contains several brief topics that do not fit anywhere +else: reading netnews, running shell commands and shell subprocesses, +using a single shared Emacs for utilities that expect to run an editor +as a subprocess, printing hardcopy, sorting text, narrowing display to +part of the buffer, editing double-column files and binary files, +saving an Emacs session for later resumption, following hyperlinks, +browsing images, emulating other editors, and various diversions and +amusements. + +@end iftex + +@ifnottex +@raisesections +@end ifnottex + +@node Gnus, Shell, Calendar/Diary, Top +@section Gnus +@cindex Gnus +@cindex reading netnews + +Gnus is an Emacs package primarily designed for reading and posting +Usenet news. It can also be used to read and respond to messages from a +number of other sources---mail, remote directories, digests, and so on. + +Here we introduce Gnus and describe several basic features. +@ifnottex +For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. +@end ifnottex +@iftex +For full details on Gnus, type @kbd{M-x info} and then select the Gnus +manual. +@end iftex + +@findex gnus +To start Gnus, type @kbd{M-x gnus @key{RET}}. + +@menu +* Buffers of Gnus:: The group, summary, and article buffers. +* Gnus Startup:: What you should know about starting Gnus. +* Summary of Gnus:: A short description of the basic Gnus commands. +@end menu + +@node Buffers of Gnus +@subsection Gnus Buffers + +Unlike most Emacs packages, Gnus uses several buffers to display +information and to receive commands. The three Gnus buffers users use +most are the @dfn{group buffer}, the @dfn{summary buffer} and the +@dfn{article buffer}. + +The @dfn{group buffer} contains a list of newsgroups. This is the +first buffer Gnus displays when it starts up. It normally displays +only the groups to which you subscribe and that contain unread +articles. Use this buffer to select a specific group. + +The @dfn{summary buffer} lists one line for each article in a single +group. By default, the author, the subject and the line number are +displayed for each article, but this is customizable, like most aspects +of Gnus display. The summary buffer is created when you select a group +in the group buffer, and is killed when you exit the group. Use this +buffer to select an article. + +The @dfn{article buffer} displays the article. In normal Gnus usage, +you see this buffer but you don't select it---all useful +article-oriented commands work in the summary buffer. But you can +select the article buffer, and execute all Gnus commands from that +buffer, if you want to. + +@node Gnus Startup +@subsection When Gnus Starts Up + +At startup, Gnus reads your @file{.newsrc} news initialization file +and attempts to communicate with the local news server, which is a +repository of news articles. The news server need not be the same +computer you are logged in on. + +If you start Gnus and connect to the server, but do not see any +newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get +a listing of all the groups. Then type @kbd{u} to toggle +subscription to groups. + +The first time you start Gnus, Gnus subscribes you to a few selected +groups. All other groups start out as @dfn{killed groups} for you; you +can list them with @kbd{A k}. All new groups that subsequently come to +exist at the news server become @dfn{zombie groups} for you; type @kbd{A +z} to list them. You can subscribe to a group shown in these lists +using the @kbd{u} command. + +When you quit Gnus with @kbd{q}, it automatically records in your +@file{.newsrc} and @file{.newsrc.eld} initialization files the +subscribed or unsubscribed status of all groups. You should normally +not edit these files manually, but you may if you know how. + +@node Summary of Gnus +@subsection Summary of Gnus Commands + +Reading news is a two-step process: + +@enumerate +@item +Choose a group in the group buffer. + +@item +Select articles from the summary buffer. Each article selected is +displayed in the article buffer in a large window, below the summary +buffer in its small window. +@end enumerate + + Each Gnus buffer has its own special commands; the meanings of any +given key in the various Gnus buffers are usually analogous, even if +not identical. Here are commands for the group and summary buffers: + +@table @kbd +@kindex q @r{(Gnus Group mode)} +@findex gnus-group-exit +@item q +In the group buffer, update your @file{.newsrc} initialization file +and quit Gnus. + +In the summary buffer, exit the current group and return to the +group buffer. Thus, typing @kbd{q} twice quits Gnus. + +@kindex L @r{(Gnus Group mode)} +@findex gnus-group-list-all-groups +@item L +In the group buffer, list all the groups available on your news +server (except those you have killed). This may be a long list! + +@kindex l @r{(Gnus Group mode)} +@findex gnus-group-list-groups +@item l +In the group buffer, list only the groups to which you subscribe and +which contain unread articles. + +@kindex u @r{(Gnus Group mode)} +@findex gnus-group-unsubscribe-current-group +@cindex subscribe groups +@cindex unsubscribe groups +@item u +In the group buffer, unsubscribe from (or subscribe to) the group listed +in the line that point is on. When you quit Gnus by typing @kbd{q}, +Gnus lists in your @file{.newsrc} file which groups you have subscribed +to. The next time you start Gnus, you won't see this group, +because Gnus normally displays only subscribed-to groups. + +@kindex C-k @r{(Gnus)} +@findex gnus-group-kill-group +@item C-k +In the group buffer, ``kill'' the current line's group---don't +even list it in @file{.newsrc} from now on. This affects future +Gnus sessions as well as the present session. + +When you quit Gnus by typing @kbd{q}, Gnus writes information +in the file @file{.newsrc} describing all newsgroups except those you +have ``killed.'' + +@kindex SPC @r{(Gnus)} +@findex gnus-group-read-group +@item @key{SPC} +In the group buffer, select the group on the line under the cursor +and display the first unread article in that group. + +@need 1000 +In the summary buffer, + +@itemize @bullet +@item +Select the article on the line under the cursor if none is selected. + +@item +Scroll the text of the selected article (if there is one). + +@item +Select the next unread article if at the end of the current article. +@end itemize + +Thus, you can move through all the articles by repeatedly typing @key{SPC}. + +@kindex DEL @r{(Gnus)} +@item @key{DEL} +In the group buffer, move point to the previous group containing +unread articles. + +@findex gnus-summary-prev-page +In the summary buffer, scroll the text of the article backwards. + +@kindex n @r{(Gnus)} +@findex gnus-group-next-unread-group +@findex gnus-summary-next-unread-article +@item n +Move point to the next unread group, or select the next unread article. + +@kindex p @r{(Gnus)} +@findex gnus-group-prev-unread-group +@findex gnus-summary-prev-unread-article +@item p +Move point to the previous unread group, or select the previous +unread article. + +@kindex C-n @r{(Gnus Group mode)} +@findex gnus-group-next-group +@kindex C-p @r{(Gnus Group mode)} +@findex gnus-group-prev-group +@kindex C-n @r{(Gnus Summary mode)} +@findex gnus-summary-next-subject +@kindex C-p @r{(Gnus Summary mode)} +@findex gnus-summary-prev-subject +@item C-n +@itemx C-p +Move point to the next or previous item, even if it is marked as read. +This does not select the article or group on that line. + +@kindex s @r{(Gnus Summary mode)} +@findex gnus-summary-isearch-article +@item s +In the summary buffer, do an incremental search of the current text in +the article buffer, just as if you switched to the article buffer and +typed @kbd{C-s}. + +@kindex M-s @r{(Gnus Summary mode)} +@findex gnus-summary-search-article-forward +@item M-s @var{regexp} @key{RET} +In the summary buffer, search forward for articles containing a match +for @var{regexp}. + +@end table + +@ignore +@node Where to Look +@subsection Where to Look Further + +@c Too many references to the name of the manual if done with xref in TeX! +Gnus is powerful and customizable. Here are references to a few +@ifnottex +additional topics: + +@end ifnottex +@iftex +additional topics in @cite{The Gnus Manual}: + +@itemize @bullet +@item +Follow discussions on specific topics.@* +See section ``Threading.'' + +@item +Read digests. See section ``Document Groups.'' + +@item +Refer to and jump to the parent of the current article.@* +See section ``Finding the Parent.'' + +@item +Refer to articles by using Message-IDs included in the messages.@* +See section ``Article Keymap.'' + +@item +Save articles. See section ``Saving Articles.'' + +@item +Have Gnus score articles according to various criteria, like author +name, subject, or string in the body of the articles.@* +See section ``Scoring.'' + +@item +Send an article to a newsgroup.@* +See section ``Composing Messages.'' +@end itemize +@end iftex +@ifnottex +@itemize @bullet +@item +Follow discussions on specific topics.@* +@xref{Threading, , Reading Based on Conversation Threads, +gnus, The Gnus Manual}. + +@item +Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}. + +@item +Refer to and jump to the parent of the current article.@* +@xref{Finding the Parent, , , gnus, The Gnus Manual}. + +@item +Refer to articles by using Message-IDs included in the messages.@* +@xref{Article Keymap, , , gnus, The Gnus Manual}. + +@item +Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}. + +@item +Have Gnus score articles according to various criteria, like author +name, subject, or string in the body of the articles.@* +@xref{Scoring, , , gnus, The Gnus Manual}. + +@item +Send an article to a newsgroup.@* +@xref{Composing Messages, , , gnus, The Gnus Manual}. +@end itemize +@end ifnottex +@end ignore + +@node Shell, Emacs Server, Gnus, Top +@section Running Shell Commands from Emacs +@cindex subshell +@cindex shell commands + + Emacs has commands for passing single command lines to inferior shell +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. + +@table @kbd +@item M-! @var{cmd} @key{RET} +Run the shell command line @var{cmd} and display the output +(@code{shell-command}). +@item M-| @var{cmd} @key{RET} +Run the shell command line @var{cmd} with region contents as input; +optionally replace the region with the output +(@code{shell-command-on-region}). +@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. +@end table + + @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It +is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell, +Eshell: The Emacs Shell}. + +@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 + +@node Single Shell +@subsection Single Shell Commands + +@kindex M-! +@findex shell-command + @kbd{M-!} (@code{shell-command}) reads a line of text using the +minibuffer and executes it as a shell command in a subshell made just +for that command. Standard input for the command comes from the null +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. You do not get any status information for an asynchronous +command, since it hasn't finished yet when @code{shell-command} returns. + +@kindex M-| +@findex shell-command-on-region + @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but +passes the contents of the region as the standard input to the shell +command, instead of no input. With a numeric argument, meaning insert +the output in the current buffer, it deletes the old region and the +output replaces it as the contents of the region. It returns the +command's exit status, like @kbd{M-!}. + + 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 the buffer +contains. + +@vindex shell-file-name + Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify +the shell to use. This variable is initialized based on your +@env{SHELL} environment variable when Emacs is started. If the file +name is relative, Emacs searches the directories in the list +@code{exec-path}; this list is initialized based on the environment +variable @env{PATH} when Emacs is started. Your @file{.emacs} file +can override either or both of these default initializations. + + 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 then 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{Communication Coding}. + +@vindex shell-command-default-error-buffer + Error output from these commands is normally intermixed with the +regular output. But if the variable +@code{shell-command-default-error-buffer} has a string as value, and +it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output +before point in that buffer. + +@node Interactive Shell +@subsection Interactive Inferior Shell + +@findex shell + To run a subshell interactively, putting its typescript in an Emacs +buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named +@samp{*shell*} and runs a subshell with input coming from and output going +to that buffer. That is to say, any ``terminal output'' from the subshell +goes into the buffer, advancing point, and any ``terminal input'' for +the subshell comes from text in the buffer. To give input to the subshell, +go to the end of the buffer and type the input, terminated by @key{RET}. + + Emacs does not wait for the subshell to do anything. You can switch +windows or buffers and edit them while the shell is waiting, or while it is +running a command. Output from the subshell waits until Emacs has time to +process it; this happens whenever Emacs is waiting for keyboard input or +for time to elapse. + +@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}. +Subshells in different buffers run independently and in parallel. + +@vindex explicit-shell-file-name +@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 @env{ESHELL} is used, or the environment +variable @env{SHELL} if there is no @env{ESHELL}. If the file name +specified is relative, the directories in the list @code{exec-path} are +searched; this list is initialized based on the environment variable +@env{PATH} when Emacs is started. Your @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}. If this file is not found, Emacs tries to fallback +on @file{~/.emacs.d/init_@var{shellname}.sh}. + + 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 change the coding system for a running subshell by typing +@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication +Coding}. + +@cindex @env{INSIDE_EMACS} environment variable + Emacs sets the envitonment variable @env{INSIDE_EMACS} to @code{t} +in the subshell. Programs can check this variable to determine +whether they are running inside an Emacs subshell. + +@cindex @env{EMACS} environment variable + Emacs also sets the @env{EMACS} environment variable to @code{t} if +it is not already defined. @strong{Warning:} This environment +variable is deprecated. Programs that check this variable should be +changed to check @env{INSIDE_EMACS} instead. + +@node Shell Mode +@subsection Shell Mode +@cindex Shell mode +@cindex mode, Shell + + Shell buffers use Shell mode, which defines several special keys +attached to the @kbd{C-c} prefix. They are chosen to resemble the usual +editing and job control characters present in shells that are not under +Emacs, except that you must type @kbd{C-c} first. Here is a complete list +of the special key bindings of Shell mode: + +@table @kbd +@item @key{RET} +@kindex RET @r{(Shell mode)} +@findex comint-send-input +At end of buffer send line as input; otherwise, copy current line to +end of buffer and send it (@code{comint-send-input}). Copying a line +in this way omits any prompt at the beginning of the line (text output +by programs preceding your input). @xref{Shell Prompts}, for how +Shell mode recognizes prompts. + +@item @key{TAB} +@kindex TAB @r{(Shell mode)} +@findex comint-dynamic-complete +Complete the command name or file name before point in the shell buffer +(@code{comint-dynamic-complete}). @key{TAB} also completes history +references (@pxref{History References}) and environment variable names. + +@vindex shell-completion-fignore +@vindex comint-completion-fignore +The variable @code{shell-completion-fignore} specifies a list of file +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 M-? +@kindex M-? @r{(Shell mode)} +@findex comint-dynamic-list-filename@dots{} +Display temporarily a list of the possible completions of the file name +before point in the shell buffer +(@code{comint-dynamic-list-filename-completions}). + +@item C-d +@kindex C-d @r{(Shell mode)} +@findex comint-delchar-or-maybe-eof +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 @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-or-process-mark +Move to the beginning of the line, but after the prompt if any +(@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 +command inserts a newline before point, but does not send the preceding +text as input to the subshell---at least, not yet. Both lines, the one +before this newline and the one after, will be sent together (along with +the newline that separates them), when you type @key{RET}. + +@item C-c C-u +@kindex C-c C-u @r{(Shell mode)} +@findex comint-kill-input +Kill all text pending at end of buffer to be sent as input +(@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)} +Kill a word before point (@code{backward-kill-word}). + +@item C-c C-c +@kindex C-c C-c @r{(Shell mode)} +@findex comint-interrupt-subjob +Interrupt the shell or its current subjob if any +(@code{comint-interrupt-subjob}). This command also kills +any shell input pending in the shell buffer and not yet sent. + +@item C-c C-z +@kindex C-c C-z @r{(Shell mode)} +@findex comint-stop-subjob +Stop the shell or its current subjob if any (@code{comint-stop-subjob}). +This command also kills any shell input pending in the shell buffer and +not yet sent. + +@item C-c C-\ +@findex comint-quit-subjob +@kindex C-c C-\ @r{(Shell mode)} +Send quit signal to the shell or its current subjob if any +(@code{comint-quit-subjob}). This command also kills any shell input +pending in the shell buffer and not yet sent. + +@item C-c C-o +@kindex C-c C-o @r{(Shell mode)} +@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 +@kindex C-c C-r @r{(Shell mode)} +@kindex C-M-l @r{(Shell mode)} +@findex comint-show-output +Scroll to display the beginning of the last batch of output at the top +of the window; also move the cursor there (@code{comint-show-output}). + +@item C-c C-e +@kindex C-c C-e @r{(Shell mode)} +@findex comint-show-maximum-output +Scroll to put the end of the buffer at the bottom of the window +(@code{comint-show-maximum-output}). + +@item C-c C-f +@kindex C-c C-f @r{(Shell mode)} +@findex shell-forward-command +@vindex shell-command-regexp +Move forward across one shell command, but not beyond the current line +(@code{shell-forward-command}). The variable @code{shell-command-regexp} +specifies how to recognize the end of a command. + +@item C-c C-b +@kindex C-c C-b @r{(Shell mode)} +@findex shell-backward-command +Move backward across one shell command, but not beyond the current line +(@code{shell-backward-command}). + +@item M-x dirs +Ask the shell what its current directory is, so that Emacs can agree +with the shell. + +@item M-x send-invisible @key{RET} @var{text} @key{RET} +@findex send-invisible +Send @var{text} as input to the shell, after reading it without +echoing. This is useful when a shell command runs a program that asks +for a password. + +Please note that Emacs will not echo passwords by default. If you +really want them to be echoed, evaluate the following Lisp +expression: + +@example +(remove-hook 'comint-output-filter-functions + 'comint-watch-for-password-prompt) +@end example + +@item M-x comint-continue-subjob +@findex comint-continue-subjob +Continue the shell process. This is useful if you accidentally suspend +the shell process.@footnote{You should not suspend the shell process. +Suspending a subjob of the shell is a completely different matter---that +is normal practice, but you must use the shell to continue the subjob; +this command won't do it.} + +@item M-x comint-strip-ctrl-m +@findex comint-strip-ctrl-m +Discard all control-M characters from the current group of shell output. +The most convenient way to use this command is to make it run +automatically when you get output from the subshell. To do that, +evaluate this Lisp expression: + +@example +(add-hook 'comint-output-filter-functions + 'comint-strip-ctrl-m) +@end example + +@item M-x comint-truncate-buffer +@findex comint-truncate-buffer +This command truncates the shell buffer to a certain maximum number of +lines, specified by the variable @code{comint-buffer-maximum-size}. +Here's how to do this automatically each time you get output from the +subshell: + +@example +(add-hook 'comint-output-filter-functions + 'comint-truncate-buffer) +@end example +@end table + +@cindex Comint mode +@cindex mode, Comint + Shell mode is a derivative of Comint mode, a general-purpose mode for +communicating with interactive subprocesses. Most of the features of +Shell mode actually come from Comint mode, as you can see from the +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}). + +@findex comint-run + You can use @kbd{M-x comint-run} to execute any program of your choice +in a subprocess using unmodified Comint mode---without the +specializations of Shell mode. + +@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 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. +* Copy: Shell History Copying. Moving to a command and then copying it. +* History References:: Expanding @samp{!}-style history references. +@end menu + +@node Shell Ring +@subsubsection Shell History Ring + +@table @kbd +@findex comint-previous-input +@kindex M-p @r{(Shell mode)} +@item M-p +@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)} +@kindex M-s @r{(Shell mode)} +@findex comint-previous-matching-input +@findex comint-next-matching-input +@item M-r @var{regexp} @key{RET} +@itemx M-s @var{regexp} @key{RET} +Search backwards or forwards for old shell commands that match @var{regexp}. + +@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 +reuse shell commands from the history, use the editing commands @kbd{M-p}, +@kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer +history commands except that they operate on the text at the end of the +shell buffer, where you would normally insert text to send to the shell. + + @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-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 +typing @key{RET}, or you can edit it first and then resubmit it if you +wish. Any partial input you were composing before navigating the +history list is restored when you go to the beginning or end of the +history ring. + + Often it is useful to reexecute several successive shell commands that +were previously executed in sequence. To do this, first find and +reexecute the first command of the sequence. Then type @kbd{C-c C-x}; +that will fetch the following command---the one that follows the command +you just repeated. Then type @key{RET} to reexecute this command. You +can reexecute several successive commands by typing @kbd{C-c C-x +@key{RET}} over and over. + + 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 +that these commands access. + +@vindex shell-input-ring-file-name + Some shells store their command histories in files so that you can +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. + +@node Shell History Copying +@subsubsection Shell History Copying + +@table @kbd +@kindex C-c C-p @r{(Shell mode)} +@findex comint-previous-prompt +@item C-c C-p +Move point to the previous prompt (@code{comint-previous-prompt}). + +@kindex C-c C-n @r{(Shell mode)} +@findex comint-next-prompt +@item C-c C-n +Move point to the following prompt (@code{comint-next-prompt}). + +@kindex C-c RET @r{(Shell mode)} +@findex comint-copy-old-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 +move point back to a previous command. After you copy the command, you +can submit the copy as input with @key{RET}. If you wish, you can +edit the copy before resubmitting it. If you use this command on an +output line, it copies that line to the end of the buffer. + +@item Mouse-2 +If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy +the old input command that you click on, inserting the copy at the end +of the buffer (@code{comint-insert-input}). If +@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is +not over old input, just yank as usual. +@end table + + Moving to a previous input and then copying it with @kbd{C-c +@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 +recognizes these constructs, and can perform the history substitution +for you. + + If you insert a history reference and type @key{TAB}, this searches +the input history for a matching command, performs substitution if +necessary, and places the result in the buffer in place of the history +reference. For example, you can fetch the most recent command +beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the +command if you wish, and then resubmit the command to the shell by +typing @key{RET}. + +@vindex comint-input-autoexpand +@findex comint-magic-space + Shell mode can optionally expand history references in the buffer +when you send them to the shell. To request this, set the variable +@code{comint-input-autoexpand} to @code{input}. You can make +@key{SPC} perform history expansion by binding @key{SPC} to the +command @code{comint-magic-space}. + + 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-to-bottom-on-input + If the variable @code{comint-scroll-to-bottom-on-input} is +non-@code{nil}, insertion and yank commands scroll the selected window +to the bottom before inserting. The default is @code{nil}. + +@vindex comint-scroll-show-maximum-output + If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then +arrival of output when point is at the end tries to scroll the last +line of text to the bottom line of the window, showing as much useful +text as possible. (This mimics the scrolling behavior of most +terminals.) The default is @code{t}. + +@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 +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} +value means to omit an input that is the same as the previous input. +The default is @code{nil}, which means to store each input even if it is +equal to the previous input. + +@vindex comint-completion-addsuffix +@vindex comint-completion-recexact +@vindex comint-completion-autolist + Three variables customize file name completion. The variable +@code{comint-completion-addsuffix} controls whether completion inserts a +space or a slash to indicate a fully completed file or directory name +(non-@code{nil} means do insert a space or slash). +@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} +to choose the shortest possible completion if the usual Emacs completion +algorithm cannot add even a single character. +@code{comint-completion-autolist}, if non-@code{nil}, says to list all +the possible completions whenever completion is not exact. + +@vindex shell-completion-execonly + Command completion normally considers only executable files. +If you set @code{shell-completion-execonly} to @code{nil}, +it considers nonexecutable files as well. + +@findex shell-pushd-tohome +@findex shell-pushd-dextract +@findex shell-pushd-dunique + You can configure the behavior of @samp{pushd}. Variables control +whether @samp{pushd} behaves like @samp{cd} if no argument is given +(@code{shell-pushd-tohome}), pop rather than rotate with a numeric +argument (@code{shell-pushd-dextract}), and only add directories to the +directory stack if they are not already on it +(@code{shell-pushd-dunique}). The values you choose should match the +underlying shell, of course. + + 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 connecting to remote host +@cindex Telnet +@cindex Rlogin + + 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} +Set up a Telnet connection to the computer named @var{hostname}. +@item M-x rlogin @key{RET} @var{hostname} @key{RET} +Set up an Rlogin connection to the computer named @var{hostname}. +@end table + +@findex telnet + Use @kbd{M-x telnet} to set up a Telnet connection to another +computer. (Telnet is the standard Internet protocol for remote login.) +It reads the host name of the other computer as an argument with the +minibuffer. Once the connection is established, talking to the other +computer works like talking to a subshell: you can edit input with the +usual Emacs commands, and send it a line at a time by typing @key{RET}. +The output is inserted in the Telnet buffer interspersed with the input. + +@findex rlogin +@vindex rlogin-explicit-args + Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is +another remote login communication protocol, essentially much like the +Telnet protocol but incompatible with it, and supported only by certain +systems. Rlogin's advantages are that you can arrange not to have to +give your user name and password when communicating between two machines +you frequently use, and that you can make an 8-bit-clean connection. +(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")} +before you run Rlogin.) + + @kbd{M-x rlogin} sets up the default file directory of the Emacs +buffer to access the remote host via FTP (@pxref{File Names}), and it +tracks the shell commands that change the current directory, just like +Shell mode. + +@findex rlogin-directory-tracking-mode + There are two ways of doing directory tracking in an Rlogin +buffer---either with remote directory names +@file{/@var{host}:@var{dir}/} or with local names (that works if the +``remote'' machine shares file systems with your machine of origin). +You can use the command @code{rlogin-directory-tracking-mode} to switch +modes. No argument means use remote directory names, a positive +argument means use local names, and a negative argument means turn +off directory tracking. + +@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 @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 @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 with 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 program and the +server that is part of Emacs. Here is how. + +@cindex @env{TEXEDIT} environment variable +@findex server-start + First, the preparations. Within Emacs, call the function +@code{server-start}. (Your @file{.emacs} init file can do this +automatically if you add the expression @code{(server-start)} to it, +see @ref{Init File}.) Then, outside 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 @env{TEXEDIT} environment +variable to @samp{emacsclient +%d %s}.) + +@pindex emacs.bash +@cindex Bash command to use Emacs server + As an alternative to using @code{emacsclient}, the file +@file{etc/emacs.bash} defines a Bash command @code{edit} which will +communicate with a running Emacs session, or start one if none exist. + +@kindex C-x # +@findex server-edit + Now, 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 +editing it in the already running Emacs session. + + 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 @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 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 specify 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 +three ways to do this: + +@itemize @bullet +@item +Using a window system, run @code{mail} and the principal Emacs in two +separate windows. While @code{mail} is waiting for @code{emacsclient}, +the window where it was running is blocked, but you can use Emacs by +switching windows. + +@item +Using virtual terminals, run @code{mail} in one virtual terminal +and run Emacs in another. + +@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. Note that server buffers created in this way are not killed +automatically when you finish with them. + +@menu +* Invoking emacsclient:: Emacs client startup options. +@end menu + +@node Invoking emacsclient,, Emacs Server, Emacs Server +@subsection Invoking @code{emacsclient} +@cindex @code{emacsclient} invocation and options + + To run the @code{emacsclient} program, specify file names as arguments, +and optionally line numbers as well, like this: + +@example +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. + + If you invoke @code{emacsclient} for more than one file, the +additional client buffers are buried at the bottom of the buffer list +(@pxref{Buffers}). If you call @kbd{C-x #} after you are done editing +a client buffer, the next client buffer is automatically selected. + + 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{-a @var{command}} or +@samp{--alternate-editor=@var{command}} specifies a command to run if +@code{emacsclient} fails to contact Emacs. This is useful when +running @code{emacsclient} in a script. For example, the following +setting for the @env{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 + +@noindent +@cindex @env{ALTERNATE_EDITOR} environment variable +The environment variable @env{ALTERNATE_EDITOR} has the same effect, with +the value of the @samp{--alternate-editor} option taking precedence. + +If you use several displays, you can tell Emacs on which display to +open the given files with the @samp{-d @var{display}} or +@samp{--display=@var{display}} option to @code{emacsclient}. This is +handy when connecting from home to an Emacs session running on your +machine at your workplace. + +If there is more than one Emacs server running, you can specify a +server name with the @samp{-s @var{name}} or +@samp{--socket-name=@var{name}} option to @code{emacsclient}. (This +option is not supported on MS-Windows.) + +You can also use @code{emacsclient} to execute any piece of Emacs Lisp +code, using the @samp{-e} or @samp{--eval} option. When this option +is given, the rest of the arguments is interpreted as a list of +expressions to evaluate, not a list of files to visit. + +@cindex @env{EMACS_SERVER_FILE} environment variable +When you start the Emacs server (by calling @code{server-start}), +Emacs creates a file with information about TCP connection to the +server: the host where Emacs is running, the port where it is +listening, and an authentication string. @code{emacsclient} uses this +information if it needs to connect to the server via TCP. By default, +the file goes in the @file{~/.emacs.d/server/} directory@footnote{On +MS-Windows, if @env{HOME} is not set or the TCP configuration file +cannot be found there, Emacs also looks for the file in the +@file{.emacs.d/server/} subdirectory of the directory pointed to by +the @env{APPDATA} environment variable.}. You can specify the file +name to use with the @samp{-f @var{file}} or +@samp{--server-file=@var{file}} options, or by setting +@env{EMACS_SERVER_FILE} environment variable to the file name. + +@node Printing, Sorting, Emacs Server, Top +@section Printing Hard Copies +@cindex hardcopy +@cindex printing + + 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 +Print hardcopy of current buffer with page headings containing the file +name and page number. +@item M-x lpr-buffer +Print hardcopy of current buffer without page headings. +@item M-x print-region +Like @code{print-buffer} but print only the current region. +@item M-x lpr-region +Like @code{lpr-buffer} but print only the current region. +@end table + +@findex print-buffer +@findex print-region +@findex lpr-buffer +@findex lpr-region +@vindex lpr-switches + The hardcopy commands (aside from the PostScript commands) pass extra +switches to the @code{lpr} program based on the value of the variable +@code{lpr-switches}. Its value should be a list of strings, each string +an option starting with @samp{-}. For example, to specify a line width +of 80 columns for all the printing you do in Emacs, set +@code{lpr-switches} like this: + +@example +(setq lpr-switches '("-w80")) +@end example + +@vindex printer-name + You can specify the printer to use by setting the variable +@code{printer-name}. + +@vindex lpr-headers-switches +@vindex lpr-commands +@vindex lpr-add-switches + The variable @code{lpr-command} specifies the name of the printer +program to run; the default value depends on your operating system type. +On most systems, the default is @code{"lpr"}. The variable +@code{lpr-headers-switches} similarly specifies the extra switches to +use to make page headers. The variable @code{lpr-add-switches} controls +whether to supply @samp{-T} and @samp{-J} options (suitable for +@code{lpr}) to the printer program: @code{nil} means don't add them. +@code{lpr-add-switches} should be @code{nil} if your printer program is +not compatible with @code{lpr}. + +@menu +* PostScript:: Printing buffers or regions as PostScript. +* PostScript Variables:: Customizing the PostScript printing commands. +* Printing Package:: An optional advanced printing interface. +@end menu + +@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. +@item M-x ps-print-region +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. +@item M-x ps-print-region-with-faces +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. +@item M-x ps-spool-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. +@item M-x ps-spool-region-with-faces +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 +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 +properties of the text being printed. + + If you are using a color display, you can print a buffer of program +code with color highlighting by turning on Font-Lock mode in that +buffer, and using @code{ps-print-buffer-with-faces}. + +@findex ps-spool-region +@findex ps-spool-buffer +@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 +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. + +@ifnottex + The following section describes variables for customizing these commands. +@end ifnottex + +@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 +@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 +@code{ps-printer-name} specifies the printer. If you don't set the +first two variables yourself, they take their initial values from +@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} +is @code{nil}, @code{printer-name} is used. + +@vindex ps-print-header + 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. + +@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 + The variable @code{ps-paper-type} specifies which size of paper to +format for; legitimate values include @code{a4}, @code{a3}, +@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, +@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, +@code{tabloid}. The default is @code{letter}. You can define +additional paper sizes by changing the variable +@code{ps-page-dimensions-database}. + +@vindex ps-landscape-mode + The variable @code{ps-landscape-mode} specifies the orientation of +printing on the page. The default is @code{nil}, which stands for +``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' +mode. + +@vindex ps-number-of-columns + The variable @code{ps-number-of-columns} specifies the number of +columns; it takes effect in both landscape and portrait mode. The +default is 1. + +@vindex ps-font-family +@vindex ps-font-size +@vindex ps-font-info-database + The variable @code{ps-font-family} specifies which font family to use +for printing ordinary text. Legitimate values include @code{Courier}, +@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and +@code{Times}. The variable @code{ps-font-size} specifies the size of +the font for ordinary text. It defaults to 8.5 points. + +@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}. + + 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. +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 @acronym{ASCII} character +sequence. + + The various sort commands differ in how they divide the text into sort +records and in which part of each record is used as the sort key. Most of +the commands make each line a separate sort record, but some commands use +paragraphs or pages as sort records. Most of the sort commands use each +entire sort record as its own sort key, but some use only a portion of the +record as the sort key. + +@findex sort-lines +@findex sort-paragraphs +@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 +text of a line. A numeric argument means sort into descending order. + +@item M-x sort-paragraphs +Divide the region into paragraphs, and sort by comparing the entire +text of a paragraph (except for leading blank lines). A numeric +argument means sort into descending order. + +@item M-x sort-pages +Divide the region into pages, and sort by comparing the entire +text of a page (except for leading blank lines). A numeric +argument means sort into descending order. + +@item M-x sort-fields +Divide the region into lines, and sort by comparing the contents of +one field in each line. Fields are defined as separated by +whitespace, so the first run of consecutive non-whitespace characters +in a line constitutes field 1, the second such run constitutes field +2, etc. + +Specify which field to sort by with a numeric argument: 1 to sort by +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 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. 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 +used for comparison comes from a fixed range of columns. See below +for an explanation. + +@item M-x reverse-region +Reverse the order of the lines in the region. This is useful for +sorting into descending order by fields or columns, since those sort +commands do not have a feature for doing that. +@end table + + For example, if the buffer contains this: + +@smallexample +On systems where clash detection (locking of files being edited) is +implemented, Emacs also checks the first time you modify a buffer +whether the file has changed on disk since it was last visited or +saved. If it has, you are asked to confirm that you want to change +the buffer. +@end smallexample + +@noindent +applying @kbd{M-x sort-lines} to the entire buffer produces this: + +@smallexample +On systems where clash detection (locking of files being edited) is +implemented, Emacs also checks the first time you modify a buffer +saved. If it has, you are asked to confirm that you want to change +the buffer. +whether the file has changed on disk since it was last visited or +@end smallexample + +@noindent +where the upper-case @samp{O} sorts before all lower-case letters. If +you use @kbd{C-u 2 M-x sort-fields} instead, you get this: + +@smallexample +implemented, Emacs also checks the first time you modify a buffer +saved. If it has, you are asked to confirm that you want to change +the buffer. +On systems where clash detection (locking of files being edited) is +whether the file has changed on disk since it was last visited or +@end smallexample + +@noindent +where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, +@samp{systems} and @samp{the}. + +@findex sort-columns + @kbd{M-x sort-columns} requires more explanation. You specify the +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 +considered part of the region, and so is all of the line the mark is in, +as well as all the lines in between. + + For example, to sort a table by information found in columns 10 to 15, +you could put the mark on column 10 in the first line of the table, and +point on column 15 in the last line of the table, and then run +@code{sort-columns}. Equivalently, you could run it with the mark on +column 15 in the first line and point on column 10 in the last line. + + This can be thought of as sorting the rectangle specified by point and +the mark, except that the text on each line to the left or right of the +rectangle moves along with the text inside the rectangle. +@xref{Rectangles}. + +@vindex sort-fold-case + Many of the sort commands ignore case differences when comparing, if +@code{sort-fold-case} is non-@code{nil}. + +@node Narrowing, Two-Column, Sorting, Top +@section Narrowing +@cindex widening +@cindex restriction +@cindex narrowing +@cindex accessible portion + + @dfn{Narrowing} means focusing in on some portion of the buffer, +making the rest temporarily inaccessible. The portion which you can +still get to is called the @dfn{accessible portion}. Canceling the +narrowing, which makes the entire buffer once again accessible, is +called @dfn{widening}. The bounds of narrowing in effect in a buffer +are called the buffer's @dfn{restriction}. + + Narrowing can make it easier to concentrate on a single subroutine or +paragraph by eliminating clutter. It can also be used to limit the +range of operation of a replace command or repeating keyboard macro. + +@table @kbd +@item C-x n n +Narrow down to between point and mark (@code{narrow-to-region}). +@item C-x n w +Widen to make the entire buffer accessible again (@code{widen}). +@item C-x n p +Narrow down to the current page (@code{narrow-to-page}). +@item C-x n d +Narrow down to the current defun (@code{narrow-to-defun}). +@end table + + When you have narrowed down to a part of the buffer, that part appears +to be all there is. You can't see the rest, you can't move into it +(motion commands won't go outside the accessible part), you can't change +it in any way. However, it is not gone, and if you save the file all +the inaccessible text will be saved. The word @samp{Narrow} appears in +the mode line whenever narrowing is in effect. + +@kindex C-x n n +@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. + +@kindex C-x n p +@findex narrow-to-page +@kindex C-x n d +@findex narrow-to-defun + Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow +down to the current page. @xref{Pages}, for the definition of a page. +@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun +containing point (@pxref{Defuns}). + +@kindex C-x n w +@findex widen + The way to cancel narrowing is to widen with @kbd{C-x n w} +(@code{widen}). This makes all text in the buffer accessible again. + + You can get information on what part of the buffer you are narrowed down +to using the @kbd{C-x =} command. @xref{Position Info}. + + Because narrowing can easily confuse users who do not understand it, +@code{narrow-to-region} is normally a disabled command. Attempting to use +this command asks for confirmation and gives you the option of enabling it; +if you enable the command, confirmation will no longer be required for +it. @xref{Disabling}. + +@node Two-Column, Editing Binary Files, Narrowing, Top +@section Two-Column Editing +@cindex two-column editing +@cindex splitting columns +@cindex columns, splitting + + Two-column mode lets you conveniently edit two side-by-side columns of +text. It uses two side-by-side windows, each showing its own +buffer. + + There are three ways to enter two-column mode: + +@table @asis +@item @kbd{@key{F2} 2} or @kbd{C-x 6 2} +@kindex F2 2 +@kindex C-x 6 2 +@findex 2C-two-columns +Enter two-column mode with the current buffer on the left, and on the +right, a buffer whose name is based on the current buffer's name +(@code{2C-two-columns}). If the right-hand buffer doesn't already +exist, it starts out empty; the current buffer's contents are not +changed. + +This command is appropriate when the current buffer is empty or contains +just one column and you want to add another column. + +@item @kbd{@key{F2} s} or @kbd{C-x 6 s} +@kindex F2 s +@kindex C-x 6 s +@findex 2C-split +Split the current buffer, which contains two-column text, into two +buffers, and display them side by side (@code{2C-split}). The current +buffer becomes the left-hand buffer, but the text in the right-hand +column is moved into the right-hand buffer. The current column +specifies the split point. Splitting starts with the current line and +continues to the end of the buffer. + +This command is appropriate when you have a buffer that already contains +two-column text, and you wish to separate the columns temporarily. + +@item @kbd{@key{F2} b @var{buffer} @key{RET}} +@itemx @kbd{C-x 6 b @var{buffer} @key{RET}} +@kindex F2 b +@kindex C-x 6 b +@findex 2C-associate-buffer +Enter two-column mode using the current buffer as the left-hand buffer, +and using buffer @var{buffer} as the right-hand buffer +(@code{2C-associate-buffer}). +@end table + + @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which +is a string that appears on each line between the two columns. You can +specify the width of the separator with a numeric argument to +@kbd{@key{F2} s}; that many characters, before point, constitute the +separator string. By default, the width is 1, so the column separator +is the character before point. + + When a line has the separator at the proper place, @kbd{@key{F2} s} +puts the text after the separator into the right-hand buffer, and +deletes the separator. Lines that don't have the column separator at +the proper place remain unsplit; they stay in the left-hand buffer, and +the right-hand buffer gets an empty line to correspond. (This is the +way to write a line that ``spans both columns while in two-column +mode'': write it in the left-hand buffer, and put an empty line in the +right-hand buffer.) + +@kindex F2 RET +@kindex C-x 6 RET +@findex 2C-newline + The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} +(@code{2C-newline}) inserts a newline in each of the two buffers at +corresponding positions. This is the easiest way to add a new line to +the two-column text while editing it in split buffers. + +@kindex F2 1 +@kindex C-x 6 1 +@findex 2C-merge + When you have edited both buffers as you wish, merge them with +@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the +text from the right-hand buffer as a second column in the other buffer. +To go back to two-column editing, use @kbd{@key{F2} s}. + +@kindex F2 d +@kindex C-x 6 d +@findex 2C-dissociate + Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, +leaving each as it stands (@code{2C-dissociate}). If the other buffer, +the one not current when you type @kbd{@key{F2} d}, is empty, +@kbd{@key{F2} d} kills it. + +@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top +@section Editing Binary Files + +@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 +lets you edit the translation. When you save the file, it is converted +automatically back to binary. + + You can also use @kbd{M-x hexl-mode} to translate an existing buffer +into hex. This is useful if you visit a file normally and then discover +it is a binary file. + + Ordinary text characters overwrite in Hexl mode. This is to reduce +the risk of accidentally spoiling the alignment of data in the file. +There are special commands for insertion. Here is a list of the +commands of Hexl mode: + +@c I don't think individual index entries for these commands are useful--RMS. +@table @kbd +@item C-M-d +Insert a byte with a code typed in decimal. + +@item C-M-o +Insert a byte with a code typed in octal. + +@item C-M-x +Insert a byte with a code typed in hex. + +@item C-x [ +Move to the beginning of a 1k-byte ``page.'' + +@item C-x ] +Move to the end of a 1k-byte ``page.'' + +@item M-g +Move to an address specified in hex. + +@item M-j +Move to an address specified in decimal. + +@item C-c C-c +Leave Hexl mode, going back to the major mode this buffer had before you +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 + + 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. + +@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 saving of the desktop +when you exit Emacs, and automatic restoration of the last saved +desktop when Emacs starts: 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-save-mode 1) +@end example + +@findex desktop-change-dir +@findex desktop-revert + If you turn on @code{desktop-save-mode} in your @file{~/.emacs}, +then 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. Starting Emacs with +the @samp{--no-init-file} option also disables desktop reloading, +since it bypasses the @file{.emacs} init file, where +@code{desktop-save-mode} is usually turned on. + +@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 +@cindex recursive editing level +@cindex editing level, recursive + + A @dfn{recursive edit} is a situation in which you are using Emacs +commands to perform arbitrary editing while in the middle of another +Emacs command. For example, when you type @kbd{C-r} inside of a +@code{query-replace}, you enter a recursive edit in which you can change +the current buffer. On exiting from the recursive edit, you go back to +the @code{query-replace}. + +@kindex C-M-c +@findex exit-recursive-edit +@cindex exiting recursive edit + @dfn{Exiting} the recursive edit means returning to the unfinished +command, which continues execution. The command to exit is @kbd{C-M-c} +(@code{exit-recursive-edit}). + + You can also @dfn{abort} the recursive edit. This is like exiting, +but also quits the unfinished command immediately. Use the command +@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. + + 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, +since being in a recursive edit is true of Emacs as a whole rather than +any particular window or buffer. + + It is possible to be in recursive edits within recursive edits. For +example, after typing @kbd{C-r} in a @code{query-replace}, you may type a +command that enters the debugger. This begins a recursive editing level +for the debugger, within the recursive editing level for @kbd{C-r}. +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} +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. +Aborting also gets out of only one level of recursive edit; it returns +immediately to the command level of the previous recursive edit. If you +wish, you can then abort the next recursive editing level. + + Alternatively, the command @kbd{M-x top-level} aborts all levels of +recursive edits, returning immediately to the top-level command reader. + + The text being edited inside the recursive edit need not be the same text +that you were editing at top level. It depends on what the recursive edit +is for. If the command that invokes the recursive edit selects a different +buffer first, that is the buffer you will edit recursively. In any case, +you can switch buffers within the recursive edit in the normal manner (as +long as the buffer-switching keys have not been rebound). You could +probably do all the rest of your editing inside the recursive edit, +visiting files and all. But this could have surprising effects (such as +stack overflow) from time to time. So remember to exit or abort the +recursive edit when you no longer need it. + + In general, we try to minimize the use of recursive editing levels in +GNU Emacs. This is because they constrain you to ``go back'' in a +particular order---from the innermost level toward the top level. When +possible, we present different activities in separate buffers so that +you can switch between them as you please. Some commands switch to a +new major mode which provides a command to switch back. These +approaches give you more flexibility to go back to unfinished tasks in +the order you choose. + +@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 +Turn on EDT emulation with the command @kbd{M-x edt-emulation-on}, +while @kbd{M-x edt-emulation-off} restores normal Emacs command +bindings. + +Most of the EDT emulation commands are keypad keys, and most standard +Emacs key bindings are still available. The EDT emulation rebindings +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 +emulation; level 1 is closest to vi itself, while level 5 departs +somewhat from strict emulation to take advantage of the capabilities of +Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you +the rest of the way and ask for the emulation level. @inforef{Top, +Viper, viper}. + +@item vi (another emulator) +@findex vi-mode +@kbd{M-x vi-mode} enters a major mode that replaces the previously +established major mode. All of the vi commands that, in real vi, enter +``input'' mode are programmed instead to return to the previous major +mode. Thus, ordinary Emacs serves as vi's ``input'' mode. + +Because vi emulation works through major modes, it does not work +to switch buffers during emulation. Return to normal Emacs first. + +If you plan to use vi emulation much, you probably want to bind a key +to the @code{vi-mode} command. + +@item vi (alternate emulator) +@findex vip-mode +@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi +more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator +is changed from ordinary Emacs so you can use @key{ESC} to go back to +emulated vi command mode. To get from emulated vi command mode back to +ordinary Emacs, type @kbd{C-z}. + +This emulation does not work through major modes, and it is possible +to switch buffers in various ways within the emulator. It is not +so necessary to assign a key to the command @code{vip-mode} as +it is with @code{vi-mode} because terminating insert mode does +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 + + 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 + @kbd{M-x dissociated-press} is a command for scrambling a file of text +either word by word or character by character. Starting from a buffer of +straight English, it produces extremely amusing output. The input comes +from the current Emacs buffer. Dissociated Press writes its output in a +buffer named @samp{*Dissociation*}, and redisplays that buffer after every +couple of lines (approximately) so you can read the output as it comes out. + + Dissociated Press asks every so often whether to continue generating +output. Answer @kbd{n} to stop it. You can also stop at any time by +typing @kbd{C-g}. The dissociation output remains in the +@samp{*Dissociation*} buffer for you to copy elsewhere if you wish. + +@cindex presidentagon + Dissociated Press operates by jumping at random from one point in the +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 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 +appropriate. Bush has made it appropriate again.} Long sample texts +produce the best results. + +@cindex againformation + A positive argument to @kbd{M-x dissociated-press} tells it to operate +character by character, and specifies the number of overlap characters. A +negative argument tells it to operate word by word, and specifies the number +of overlap words. In this mode, whole words are treated as the elements to +be permuted, rather than characters. No argument is equivalent to an +argument of two. For your againformation, the output goes only into the +buffer @samp{*Dissociation*}. The buffer you start with is not changed. + +@cindex Markov chain +@cindex ignoriginal +@cindex techniquitous + Dissociated Press produces results fairly like those of a Markov +chain based on a frequency table constructed from the sample text. It +is, however, an independent, ignoriginal invention. Dissociated Press +techniquitously copies several consecutive characters from the sample +between random choices, whereas a Markov chain would choose randomly +for each word or character. This makes for more plausible sounding +results, and runs faster. + +@cindex outragedy +@cindex buggestion +@cindex properbose +@cindex mustatement +@cindex developediment +@cindex userenced + It is a mustatement that too much use of Dissociated Press can be a +developediment to your real work, sometimes to the point of outragedy. +And keep dissociwords out of your documentation, if you want it to be well +userenced and properbose. Have fun. Your buggestions are welcome. + +@node Amusements, Customization, Dissociated Press, Top +@section Other Amusements +@cindex boredom +@findex hanoi +@findex yow +@findex gomoku +@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 +bored, try an argument of 9. Sit back and watch. + +@cindex Go Moku + If you want a little more personal involvement, try @kbd{M-x gomoku}, +which plays the game Go Moku with you. + +@findex blackbox +@findex mpuz +@findex 5x5 +@cindex puzzles + @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are 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. 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