Mercurial > emacs
changeset 84179:51005891840f
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:38:43 +0000 |
| parents | 21ae5eccfd57 |
| children | 5dca7a89aae8 |
| files | man/misc.texi |
| diffstat | 1 files changed, 0 insertions(+), 2559 deletions(-) [+] |
line wrap: on
line diff
--- a/man/misc.texi Thu Sep 06 04:38:38 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,2559 +0,0 @@ -@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