@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 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c 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.
+else: viewing ``document files'', reading netnews, running shell
+commands and shell subprocesses, using a single shared Emacs for
+utilities that expect to run an editor as a subprocess, printing
+hardcopy, sorting text, narrowing display to part of the buffer,
+editing double-column files and binary files, saving an Emacs session
+for later resumption, following hyperlinks, browsing images, emulating
+other editors, and various diversions and amusements.
@end iftex
@raisesections
@end ifnottex
-@node Gnus, Shell, Calendar/Diary, Top
+@node Document View, Gnus, Calendar/Diary, Top
+@section Document Viewing
+@cindex DVI file
+@cindex PDF file
+@cindex PS file
+@cindex Postscript file
+@cindex DocView mode
+@cindex mode, DocView
+@cindex document viewer (DocView)
+@findex doc-view-mode
+
+DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript
+(PS), and PDF documents. It provides features such as slicing,
+zooming, and searching inside documents. It works by converting the
+document to a set of images using the @command{gs} (GhostScript)
+command, and displaying those images.
+
+@findex doc-view-toggle-display
+@findex doc-view-toggle-display
+@cindex doc-view-minor-mode
+ When you visit a PDF or DVI file, Emacs automatically switches to
+DocView mode. When you visit a Postscript file, Emacs switches to PS
+mode, a major mode for editing Postscript files as text; however, it
+also enables DocView minor mode, so you can type @kbd{C-c C-c} to view
+the document with DocView. (PDF and DVI files, unlike Postscript
+files, are not usually human-editable.) In either case, repeating
+@kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView
+and the file text.
+
+ You can explicitly toggle DocView mode with the command @code{M-x
+doc-view-mode}, and DocView minor mode with the command @code{M-x
+doc-view-minor-mode}.
+
+ When DocView mode starts, it displays a welcome screen and begins
+formatting the file, page by page. It displays the first page once
+that has been formatted.
+
+@findex doc-view-enlarge
+@findex doc-view-shrink
+@vindex doc-view-resolution
+ When in DocView mode, you can enlarge or shrink the document with
+@kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
+(@code{doc-view-shrink}). To specify the default size for DocView,
+set or customize the variable @code{doc-view-resolution}.
+
+ To kill the DocView buffer, type @kbd{k}
+(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q}
+(@code{quit-window}).
+
+@menu
+* Navigation:: Navigation inside DocView buffers.
+* Searching:: Searching inside documents.
+* Slicing:: Specifying which part of pages should be displayed.
+* Conversion:: Influencing and triggering conversion.
+@end menu
+
+@node Navigation
+@subsection Navigation
+
+When in DocView mode, you can scroll the current page using the usual
+Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and
+the arrow keys.
+
+@vindex doc-view-continuous
+ By default, the line-motion keys @kbd{C-p} and @kbd{C-n} stop
+scrolling at the beginning and end of the current page, respectively.
+However, if you change the variable @code{doc-view-continuous} to a
+non-@code{nil} value, then @kbd{C-p} displays the previous page if you
+are already at the beginning of the current page, and @kbd{C-n}
+displays the next page if you are at the end of the current page.
+
+@findex doc-view-next-page
+@findex doc-view-previous-page
+ You can also display the next page by typing @kbd{n}, @key{next} or
+@kbd{C-x ]} (@code{doc-view-next-page}). To display the previous
+page, type @kbd{p}, @key{prior} or @kbd{C-x [}
+(@code{doc-view-previous-page}).
+
+@findex doc-view-scroll-up-or-next-page
+@findex doc-view-scroll-down-or-previous-page
+ The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a
+convenient way to advance through the document. It scrolls within the
+current page or advances to the next. @key{DEL} moves backwards in a
+similar way (@code{doc-view-scroll-down-or-previous-page}).
+
+@findex doc-view-first-page
+@findex doc-view-last-page
+@findex doc-view-goto-page
+ To go to the first page, type @kbd{M-<}
+(@code{doc-view-first-page}); to go to the last one, type @kbd{M->}
+(@code{doc-view-last-page}). To jump to a page by its number, type
+@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}).
+
+@node Searching
+@subsection Searching
+
+While in DocView mode, you can search the file's text for a regular
+expression (@pxref{Regexps}). The interface for searching is inspired
+by @code{isearch} (@pxref{Incremental Search}).
+
+@findex doc-view-search
+@findex doc-view-search-backward
+@findex doc-view-show-tooltip
+ To begin a search, type @kbd{C-s} (@code{doc-view-search}) or
+@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular
+expression using a minibuffer, then echoes the number of matches found
+within the document. You can move forward and back among the matches
+by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show
+the match inside the page image; instead, it displays a tooltip (at
+the mouse position) listing all matching lines in the current page.
+To force display of this tooltip, type @kbd{C-t}
+(@code{doc-view-show-tooltip}).
+
+ To start a new search, use the search command with a prefix
+argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r}
+for a backward search.
+
+@node Slicing
+@subsection Slicing
+
+Documents often have wide margins for printing. They are annoying
+when reading the document on the screen, because they use up screen
+space and can cause inconvenient scrolling.
+
+@findex doc-view-set-slice
+@findex doc-view-set-slice-using-mouse
+ With DocView you can hide these margins by selecting a @dfn{slice}
+of pages to display. A slice is a rectangle within the page area;
+once you specify a slice in DocView, it applies to whichever page you
+look at.
+
+ To specify the slice numerically, type @kbd{s s}
+(@code{doc-view-set-slice}); then enter the top left pixel position
+and the slice's width and height.
+@c ??? how does this work?
+
+ A more convenient graphical way to specify the slice is with @kbd{s
+m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to
+select the slice.
+@c ??? How does this work?
+
+@findex doc-view-reset-slice
+ To cancel the selected slice, type @kbd{s r}
+(@code{doc-view-reset-slice}). Then DocView shows the entire page
+including its entire margins.
+
+@node Conversion
+@subsection Conversion
+
+@vindex doc-view-cache-directory
+@findex doc-view-clear-cache
+For efficiency, DocView caches the images produced by @command{gs}.
+The name of this directory is given by the variable
+@code{doc-view-cache-directory}. You can clear the cache directory by
+typing @code{M-x doc-view-clear-cache}.
+
+@findex doc-view-kill-proc
+@findex doc-view-kill-proc-and-buffer
+ To force a reconversion of the currently viewed document, type
+@kbd{r} or @kbd{g} (@code{revert-buffer}). To kill the converter
+process associated with the current buffer, type @kbd{K}
+(@code{doc-view-kill-proc}). The command @kbd{k}
+(@code{doc-view-kill-proc-and-buffer}) kills the converter process and
+the DocView buffer.
+
+ The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
+(@code{doc-view-shrink}) need to reconvert the document at the new
+size. The current page is converted first.
+
+@node Gnus, Shell, Document View, 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
+For full details on Gnus, type @kbd{C-h i} and then select the Gnus
manual.
@end iftex
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-& @var{cmd} @key{RET}
+Run the shell command line @var{cmd} asynchronously, and display the
+output (@code{async-shell-command}).
@item M-x shell
Run a subshell with input and output through an Emacs buffer.
You can then give commands interactively.
* Term Mode:: Special Emacs commands used in Term mode.
* Paging in Term:: Paging in the terminal emulator.
* Remote Host:: Connecting to another computer.
+* Serial Terminal:: Connecting to a serial port.
@end menu
@node Single Shell
program. You do not get any status information for an asynchronous
command, since it hasn't finished yet when @code{shell-command} returns.
+ You can also type @kbd{M-&} (@code{async-shell-command}) to execute
+a shell command asynchronously. This behaves exactly like calling
+@code{shell-command} with @samp{&}, except that you do not need to add
+the @samp{&} to the shell command line.
+
@kindex M-|
@findex shell-command-on-region
@kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but
@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.
+variable @env{PATH} when Emacs is started. Your init file can
+override either or both of these default initializations (@pxref{Init
+File}).
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
@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}.
+ To run a subshell interactively, use @kbd{M-x shell}. This creates
+(or reuses) a buffer named @samp{*shell*} and runs a subshell with
+input coming from and output going to that buffer. That is to say,
+any ``terminal output'' from the subshell goes into the buffer,
+advancing point, and any ``terminal input'' for the subshell comes
+from text in the buffer. To give input to the subshell, go to the end
+of the buffer and type the input, terminated by @key{RET}.
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
@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.
+@code{explicit-shell-file-name}, if that is non-@code{nil}.
+Otherwise, the environment variable @env{ESHELL} is used, or the
+environment variable @env{SHELL} if there is no @env{ESHELL}. If the
+file name specified is relative, the directories in the list
+@code{exec-path} are searched; this list is initialized based on the
+environment variable @env{PATH} when Emacs is started. Your init file
+can override either or both of these default initializations.
+(@pxref{Init File}).
Emacs sends the new shell the contents of the file
@file{~/.emacs_@var{shellname}} as input, if it exists, where
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}.
+@findex comint-history-isearch-backward-regexp
+@item M-r
+Begin an incremental regexp search of old shell commands.
@item C-c C-x
@kindex C-c C-x @r{(Shell mode)}
@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
+ The history search command @kbd{M-r} begins an incremental regular
+expression search of previous shell commands. After typing @kbd{M-r},
+start typing the desired string or regular expression; the last
+matching shell command will be displayed in the current line.
+Incremental search commands have their usual effects---for instance,
+@kbd{C-s} and @kbd{C-r} search forward and backward for the next match
+(@pxref{Incremental Search}). When you find the desired input, type
+@key{RET} to terminate the search. This puts the input in the command
+line. Any partial input you were composing before navigating the
history list is restored when you go to the beginning or end of the
history ring.
@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.
+Copy the input command at point, inserting the copy at the end of the
+buffer (@code{comint-copy-old-input}). This is useful if you move
+point back to a previous command. After you copy the command, you can
+submit the copy as input with @key{RET}. If you wish, you can edit
+the copy before resubmitting it. If you use this command on an output
+line, it copies that line to the end of the buffer.
@item Mouse-2
If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy
(@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.
+ To run a subshell in a terminal emulator, use @kbd{M-x term}. This
+creates (or reuses) a buffer named @samp{*terminal*}, and runs a
+subshell with input coming from your keyboard, and output going to
+that buffer.
The terminal emulator uses Term mode, which has two input modes. In
line mode, Term basically acts like Shell mode; see @ref{Shell Mode}.
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
+ You can use Term mode to communicate with a device connected to a
+serial port of your computer. @xref{Serial Terminal}.
+
+ 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.
@end ignore
+@node Serial Terminal
+@subsection Serial Terminal
+@cindex terminal, serial
+@findex serial-term
+
+ If you have a device connected to a serial port of your computer,
+you can use Emacs to communicate with it. @kbd{M-x serial-term} will
+ask you for a serial port name and speed and will then open a new
+window in @ref{Term Mode}.
+
+ The speed of the serial port is measured in bits per second. The
+most common speed is 9600 bits per second. You can change the speed
+interactively by clicking on the mode line.
+
+ A serial port can be configured even more by clicking on ``8N1'' in
+the mode line. By default, a serial port is configured as ``8N1'',
+which means that each byte consists of 8 data bits, No parity check
+bit, and 1 stopbit.
+
+ When you have opened the serial port connection, you will see output
+from the device in the window. Also, what you type in the window is
+sent to the device.
+
+ If the speed or the configuration is wrong, you cannot communicate
+with your device and will probably only see garbage output in the
+window.
+
@node Emacs Server, Printing, Shell, Top
@section Using Emacs as a Server
@pindex emacsclient
@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.
+ Various programs such as @command{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 way, by starting a new Emacs process. This is
+inconvenient because the new Emacs process doesn't share buffers, a
+command history, or other kinds of information 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.
+ You can solve this problem by setting up Emacs as an @dfn{edit
+server}, so that it ``listens'' for external edit requests and acts
+accordingly. There are two ways to start an Emacs server:
-@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.
+ The first is to run the command @code{server-start} in an existing
+Emacs process: either type @kbd{M-x server-start}, or put the
+expression @code{(server-start)} in your initialization file
+(@pxref{Init File}). The existing Emacs process is the server; when
+you exit Emacs, the server dies with the Emacs process.
+
+@cindex daemon, Emacs
+ The second way to start an Emacs server is to run Emacs as a
+@dfn{daemon}, using the @samp{--daemon} command-line option.
+@xref{Initial Options}. When Emacs is started this way, it calls
+@code{server-start} after initialization, and returns control to the
+calling terminal instead of opening an initial frame; it then waits in
+the background, listening for edit requests.
-@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.
+@cindex @env{TEXEDIT} environment variable
+ Once an Emacs server is set up, you can use a shell command called
+@command{emacsclient} to connect to the existing Emacs process and
+tell it to visit a file. If you set the @env{EDITOR} environment
+variable to @samp{emacsclient}, programs such as @command{mail} will
+use the existing Emacs process for editing.@footnote{Some programs use
+a different environment variable; for example, to make @TeX{} use
+@samp{emacsclient}, set the @env{TEXEDIT} environment variable to
+@samp{emacsclient +%d %s}.}
@vindex server-name
You can run multiple Emacs servers on the same machine by giving
@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}.
+name, using the @samp{-s} option (@pxref{emacsclient Options}).
- 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:
+@menu
+* Invoking emacsclient:: Connecting to the Emacs server.
+* emacsclient Options:: Emacs client startup options.
+@end menu
-@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.
+@node Invoking emacsclient
+@subsection Invoking @code{emacsclient}
+@cindex @code{emacsclient} invocation
+
+ The simplest way to use the @command{emacsclient} program is to run
+the shell command @samp{emacsclient @var{file}}, where @var{file} is a
+file name. This connects to an Emacs server, and tells that Emacs
+process to visit @var{file} in one of its existing frames---either a
+graphical frame, or one in a text-only terminal (@pxref{Frames}). You
+can then select that frame to begin editing.
+
+ If there is no Emacs server, the @command{emacsclient} program halts
+with an error message. If the Emacs process has no existing
+frame---which can happen if it was started as a daemon (@pxref{Emacs
+Server})---then Emacs opens a frame on the terminal in which you
+called @command{emacsclient}.
+
+ You can also force @command{emacsclient} to open a new frame on a
+graphical display, or on a text-only terminal, using the @samp{-c} and
+@samp{-t} options. @xref{emacsclient Options}.
+
+ If you are running on a single text-only terminal, you can switch
+between @command{emacsclient}'s shell and the Emacs server using one
+of two methods: (i) run the Emacs server and @command{emacsclient} on
+different virtual terminals, and switch to the Emacs server's virtual
+terminal after calling @command{emacsclient}; or (ii) call
+@command{emacsclient} from within the Emacs server itself, using Shell
+mode (@pxref{Interactive Shell}) or Term mode (@pxref{Term Mode});
+@code{emacsclient} blocks only the subshell under Emacs, and you can
+still use Emacs to edit the file.
-@item
-Using virtual terminals, run @code{mail} in one virtual terminal
-and run Emacs in another.
+@kindex C-x #
+@findex server-edit
+ When you finish editing @var{file} in the Emacs server, type
+@kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file
+and sends a message back to the @command{emacsclient} program, telling
+it to exit. Programs that use @env{EDITOR} usually wait for the
+``editor''---in the case @command{emacsclient}---to exit before doing
+something else.
+
+ You can also call @command{emacsclient} with multiple file name
+arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the
+Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs
+selects the buffer visiting @var{file1}, and buries the other buffers
+at the bottom of the buffer list (@pxref{Buffers}). The
+@command{emacsclient} program exits once all the specified files are
+finished (i.e., once you have typed @kbd{C-x #} in each server
+buffer).
-@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
+@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 was 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.
- 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.
+ Each @kbd{C-x #} 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 tell
+@command{emacsclient} that you are finished.
-@menu
-* Invoking emacsclient:: Emacs client startup options.
-@end menu
+@vindex server-window
+ If you set the value of the variable @code{server-window} to a
+window or a frame, @kbd{C-x #} always displays the next server buffer
+in that window or in that frame.
-@node Invoking emacsclient,, Emacs Server, Emacs Server
-@subsection Invoking @code{emacsclient}
-@cindex @code{emacsclient} invocation and options
+@node emacsclient Options
+@subsection @code{emacsclient} Options
+@cindex @code{emacsclient} options
- To run the @code{emacsclient} program, specify file names as arguments,
-and optionally line numbers as well, like this:
+ You can pass some optional arguments to the @command{emacsclient}
+program, such as:
@example
-emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
+emacsclient -c +12 @var{file1} +4:3 @var{file2}
@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:
+The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments
+specify line numbers, or line and column numbers, for the next file
+argument. These behave like the command line arguments for Emacs
+itself. @xref{Action Arguments}.
+
+ The other optional arguments recognized by @command{emacsclient} are
+listed below:
+
+@table @samp
+@item -a @var{command}
+@itemx --alternate-editor=@var{command}
+Specify 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.
+As a special exception, if @var{command} is the empty string, then
+@code{emacsclient} starts Emacs in daemon mode and then tries
+connecting again.
-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.)
+@cindex @env{ALTERNATE_EDITOR} environment variable
+The environment variable @env{ALTERNATE_EDITOR} has the same effect as
+the @samp{-a} option. If both are present, the latter takes
+precedence.
+
+@item -c
+Create a new graphical frame, instead of using an existing Emacs
+frame. Emacs 23 can create a graphical frame even if it was started
+in a text-only terminal, provided it is able to connect to a graphical
+display. If no graphical display is available, Emacs creates a new
+text-only terminal frame (@pxref{Frames}). If you omit a filename
+argument while supplying the @samp{-c} option, the new frame displays
+the @samp{*scratch*} buffer (@pxref{Buffers}).
+
+@item -d @var{display}
+@itemx --display=@var{display}
+Tell Emacs to open the given files on the X display @var{display}
+(assuming there is more than one X display available).
+
+@item -e
+@itemx --eval
+Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some
+files. When this option is given, the arguments to
+@command{emacsclient} are interpreted as a list of expressions to
+evaluate, @emph{not} as a list of files to visit.
+
+@item -f @var{server-file}
+@itemx --server-file=@var{server-file}
+@cindex @env{EMACS_SERVER_FILE} environment variable
+@cindex server file
+@vindex server-use-tcp
+@vindex server-host
+Specify a @dfn{server file} for connecting to an Emacs server via TCP.
+
+An Emacs server usually uses an operating system feature called a
+``local socket'' to listen for connections. Some operating systems,
+such as Microsoft Windows, do not support local sockets; in that case,
+Emacs uses TCP instead. When you start the Emacs server, Emacs
+creates a server file containing some TCP information that
+@command{emacsclient} needs for making the connection. By default,
+the server file is in @file{~/.emacs.d/server/}. On Microsoft
+Windows, if @command{emacsclient} does not find the server file there,
+it looks in the @file{.emacs.d/server/} subdirectory of the directory
+pointed to by the @env{APPDATA} environment variable. You can tell
+@command{emacsclient} to use a specific server file with the @samp{-f}
+or @samp{--server-file} option, or by setting the
+@env{EMACS_SERVER_FILE} environment variable.
+
+Even if local sockets are available, you can tell Emacs to use TCP by
+setting the variable @code{server-use-tcp} to @code{t}. One advantage
+of TCP is that the server can accept connections from remote machines.
+For this to work, you must (i) set the variable @code{server-host} to
+the hostname or IP address of the machine on which the Emacs server
+runs, and (ii) provide @command{emacsclient} with the server file.
+(One convenient way to do the latter is to put the server file on a
+networked file system such as NFS.)
+
+@item -n
+@itemx --no-wait
+Let @command{emacsclient} exit immediately, instead of waiting until
+all server buffers are finished. You can take as long as you like to
+edit the server buffers within Emacs, and they are @emph{not} killed
+when you type @kbd{C-x #} in them.
+
+@item -s @var{server-name}
+@itemx --socket-name=@var{server-name}
+Connect to the Emacs server named @var{server-name}. The server name
+is given by the variable @code{server-name} on the Emacs server. If
+this option is omitted, @command{emacsclient} connects to the first
+server it finds. (This option is not supported on MS-Windows.)
+
+@item -t
+@itemx --tty
+@itemx -nw
+Create a new Emacs frame on the current text-only terminal, instead of
+using an existing Emacs frame. Emacs 23 can open a text-only terminal
+even if it was started in another text-only terminal, or on a
+graphical display. If you omit a filename argument while supplying
+this option, the new frame displays the @samp{*scratch*} buffer.
+@xref{Buffers}.
+@end table
-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.
+ If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an
+Emacs frame created with @command{emacsclient}, via the @samp{-c} or
+@samp{-t} options, Emacs deletes the frame instead of killing the
+Emacs process itself. On a text-only terminal frame created with the
+@samp{-t} option, this returns control to the terminal. Emacs also
+marks all the server buffers for the client as finished, as though you
+had typed @kbd{C-x #} in all of them.
-@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.
+ When Emacs is started as a daemon, all frames are considered client
+frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs
+process, type @kbd{M-x kill-emacs}.
@node Printing, Sorting, Emacs Server, Top
@section Printing Hard Copies
Print hardcopy of the current region in PostScript form, showing the
faces used in the text.
@item M-x ps-spool-buffer
-Generate PostScript for the current buffer text.
+Generate and spool a PostScript image for the current buffer text.
@item M-x ps-spool-region
-Generate PostScript for the current region.
+Generate and spool a PostScript image for the current region.
@item M-x ps-spool-buffer-with-faces
-Generate PostScript for the current buffer, showing the faces used.
+Generate and spool a PostScript image for the current buffer, showing the faces used.
@item M-x ps-spool-region-with-faces
-Generate PostScript for the current region, showing the faces used.
+Generate and spool a PostScript image for the current region, showing the faces used.
+@item M-x ps-despool
+Send the spooled PostScript to the printer.
@item M-x handwrite
-Generates/prints PostScript for the current buffer as if handwritten.
+Generate/print PostScript for the current buffer as if handwritten.
@end table
@findex ps-print-region
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.
+properties of the text being printed. The @samp{-with-faces} commands only
+work if they are used in a window system, so it has a way to determine color
+values.
+
+ Interactively, when you use a prefix argument (@kbd{C-u}), the command
+prompts the user for a file name, and saves the PostScript image in that file
+instead of sending it to the printer.
+
+ Noninteractively, the argument @var{filename} is treated as follows: if it is
+@code{nil}, send the image to the printer. If @var{filename} is a string, save
+the PostScript image in a file with that name.
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
@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}
+ 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.
+ Use the command @code{ps-despool} to send the spooled images to the printer.
+
+@findex ps-despool
+ This command sends the PostScript generated by @samp{-spool-} commands (see
+commands above) to the printer.
+
+ Interactively, when you use a prefix argument (@kbd{C-u}), the command
+prompts the user for a file name, and saves the spooled PostScript image in
+that file instead of sending it to the printer.
+
+ Noninteractively, the argument @var{filename} is treated as follows: if it is
+@code{nil}, send the image to the printer. If @var{filename} is a string, save
+the PostScript image in a file with that name.
+
@findex handwrite
@cindex handwriting
@kbd{M-x handwrite} is more frivolous. It generates a PostScript
with shades of gray. This might produce illegible output, even if your
screen colors only use shades of gray.
+ Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to
+print colors on black/white printers.
+
@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
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:
+sessions, or add this line in your init file (@pxref{Init File}):
@example
(desktop-save-mode 1)
@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.
+ If you turn on @code{desktop-save-mode} in your init file, 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.
+since it bypasses the 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.
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.
+recursive edits, returning immediately to the top-level command
+reader. It also exits the minibuffer, if it is active.
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
@menu
* Browse-URL:: Following URLs.
-* Goto-address:: Activating URLs.
+* Goto Address mode:: Activating URLs.
* FFAP:: Finding files etc. at point.
@end menu
Browse-URL, so that the customization options for Browse-URL will
affect all browsing in Emacs.
-@node Goto-address
+@node Goto Address mode
@subsection Activating URLs
-@findex goto-address
-@cindex Goto-address
+@findex goto-address-mode
+@cindex Goto Address mode
@cindex URLs, activating
@table @kbd
-@item M-x goto-address
+@item M-x goto-address-mode
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.
-
+goto-address-mode}. This minor mode finds all the URLs in the buffer,
+highlights them, and turns them into @dfn{buttons}: if you click on a
+URL with @kbd{Mouse-1} or @kbd{Mouse-2} (@pxref{Mouse References}), or
+move to the URL and type @kbd{C-c @key{RET}}, that displays 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-mode} to mode hooks and
+the hooks used to display an incoming message (e.g.,
+@code{rmail-show-message-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
@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.
+ 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 buffer, it might spot the `ent' in
+`pentagon' and continue from there, producing `presidentagon'. Long
+sample texts produce the best results.
@cindex againformation
A positive argument to @kbd{M-x dissociated-press} tells it to operate
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.
+text between random jumps, unlike a Markov chain which would jump
+randomly after each word or character. This makes for more plausible
+sounding results, and runs faster.
@cindex outragedy
@cindex buggestion