@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 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@iftex
@chapter Miscellaneous Commands
number of other sources---mail, remote directories, digests, and so on.
Here we introduce Gnus and describe several basic features.
-@ifinfo
+@ifnottex
For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}.
-@end ifinfo
+@end ifnottex
@iftex
For full details on Gnus, type @kbd{M-x info} and then select the Gnus
manual.
@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
-@ifinfo
+@ifnottex
additional topics:
-@end ifinfo
+@end ifnottex
@iftex
additional topics in @cite{The Gnus Manual}:
See section ``Composing Messages.''
@end itemize
@end iftex
-@ifinfo
+@ifnottex
@itemize @bullet
@item
Follow discussions on specific topics.@*
Send an article to a newsgroup.@*
@xref{Composing Messages, , , gnus, The Gnus Manual}.
@end itemize
-@end ifinfo
+@end ifnottex
@end ignore
@node Shell, Emacs Server, Gnus, Top
@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}.
+@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
@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
- Unless the environment variable @env{EMACS} is already defined,
-Emacs defines it in the subshell, with value @code{t}. A shell script
-can check this variable to determine whether it has been run from an
-Emacs subshell.
+ 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
Move point to the following prompt (@code{comint-next-prompt}).
@kindex C-c RET @r{(Shell mode)}
-@findex comint-insert-input
+@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-insert-input}). This is useful if you
+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.
+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
-Copy the input command that you click on, inserting the copy at the end
-of the buffer.
+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
@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 place the last line of
-text at the bottom line of the window, so as to show as much useful
+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}.
@env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an
inconvenient fashion, by starting a new, separate Emacs process. This
is inconvenient because it takes time and because the new Emacs process
-doesn't share the buffers in any existing 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 and Emacs server
-programs. Here is how.
+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
- First, the preparation. Within Emacs, call the function
-@code{server-start}. (Your @file{.emacs} file can do this automatically
-if you add the expression @code{(server-start)} to it.) Then, outside
-Emacs, set the @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}.)
+@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
- Then, whenever any program invokes your specified @env{EDITOR}
+ 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.
+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
each one a unique ``server name'', using the variable
@code{server-name}. For example, @kbd{M-x set-variable @key{RET}
server-name @key{RET} foo @key{RET}} sets the server name to
-@samp{foo}. The @code{emacsclient} program can visit a server by name
-using the @samp{-s} option. @xref{Invoking emacsclient}.
+@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
@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. Do it like this:
+and optionally line numbers as well, like this:
@example
emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{}
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{--alternate-editor=@var{command}} is useful when
-running @code{emacsclient} in a script. It specifies a command to run
-if @code{emacsclient} fails to contact Emacs. For example, the
-following setting for the @var{EDITOR} environment variable will
-always give you an editor, even if no Emacs server is running:
+ 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
-The environment variable @var{ALTERNATE_EDITOR} has the same effect, but
-the value of the @samp{--alternate-editor} takes precedence.
-
-@pindex emacs.bash
- Alternatively, the file @file{etc/emacs.bash} defines a bash
-function which will communicate with a running Emacs server, or start
-one if none exists.
+@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 option @samp{--display=@var{DISPLAY}}.
-This can be used typically when connecting from home to an Emacs
-server running on your machine at your workplace.
+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 option @samp{-s @var{name}}.
+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 option @samp{--eval}. When this option is given, the
-rest of the arguments is not taken as a list of files to visit but as
-a list of expressions to evaluate.
+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
can be customized in group @code{handwrite}. This function only
supports ISO 8859-1 characters.
-@ifinfo
+@ifnottex
The following section describes variables for customizing these commands.
-@end ifinfo
+@end ifnottex
@node PostScript Variables, Printing Package, PostScript, Printing
@section Variables for PostScript Hardcopy
Many of the sort commands ignore case differences when comparing, if
@code{sort-fold-case} is non-@code{nil}.
-@node Narrowing, Diff Mode, Sorting, Top
+@node Narrowing, Two-Column, Sorting, Top
@section Narrowing
@cindex widening
@cindex restriction
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 amount of narrowing in effect in a buffer at
-any time is called the buffer's @dfn{restriction}.
+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 restrict the
+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
if you enable the command, confirmation will no longer be required for
it. @xref{Disabling}.
-@node Diff Mode, Two-Column, Narrowing, Top
-@section Diff Mode
-@cindex Diff mode
-
- Diff mode is useful for editing patches and comparisons produced by
-the @command{diff} program. You can select Diff mode by typing
-@kbd{M-x diff-mode}; Emacs commands that compare files automatically
-select Diff mode. @xref{Top,, Diff, diff, Comparing and Merging Files},
-for more information about @command{diff} output formats.
-
- One general feature of Diff mode is that manual edits to the patch
-automatically correct line numbers, including those in the hunk
-header, so that you can actually apply the edited patch. Diff mode
-also provides the following commands to navigate, manipulate and apply
-parts of patches:
-
-@table @kbd
-@item M-n
-Move to the next hunk-start (@code{diff-hunk-next}).
-
-@item M-p
-Move to the previous hunk-start (@code{diff-hunk-prev}).
-
-@item M-@}
-Move to the next file-start, in a multi-file patch
-(@code{diff-file-next}).
-
-@item M-@{
-Move to the previous file-start, in a multi-file patch
-(@code{diff-file-prev}).
-
-@item M-k
-Kill the hunk at point (@code{diff-hunk-kill}).
-
-@item M-K
-In a multi-file patch, kill the current file part.
-(@code{diff-file-kill}).
-
-@item C-c C-a
-Apply this hunk to its target file (@code{diff-apply-hunk}). With a
-prefix argument of @kbd{C-u}, revert this hunk.
-
-@item C-c C-c
-Go to the source corresponding to this hunk (@code{diff-goto-source}).
-
-@item C-c C-e
-Start an Ediff session with the patch (@code{diff-ediff-patch}).
-@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
-
-@item C-c C-n
-Restrict the view to the current hunk (@code{diff-restrict-view}).
-@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the
-view to the current patch of a multiple file patch. To widen again,
-use @kbd{C-x n w}.
-
-@item C-c C-r
-Reverse the direction of comparison for the entire buffer
-(@code{diff-reverse-direction}).
-
-@item C-c C-s
-Split the hunk at point (@code{diff-split-hunk}). This is for
-manually editing patches, and only works with the unified diff format.
-
-@item C-c C-u
-Convert the entire buffer to unified format
-(@code{diff-context->unified}). With a prefix argument, convert
-unified format to context format. In Transient Mark mode, when the
-mark is active, this command operates only on the region.
-
-@item C-c C-w
-Refine the current hunk so that it disregards changes in whitespace
-(@code{diff-refine-hunk}).
-@end table
-
- @kbd{C-x 4 a} in Diff mode operates on behalf of the target file,
-but gets the function name from the patch itself. @xref{Change Log}.
-This is useful for making log entries for functions that are deleted
-by the patch.
-
-@node Two-Column, Editing Binary Files, Diff Mode, Top
+@node Two-Column, Editing Binary Files, Narrowing, Top
@section Two-Column Editing
@cindex two-column editing
@cindex splitting columns
@findex desktop-save
@vindex desktop-save-mode
You can save the desktop manually with the command @kbd{M-x
-desktop-save}. You can also enable automatic desktop saving when
-you exit Emacs: use the Customization buffer (@pxref{Easy
+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:
@findex desktop-change-dir
@findex desktop-revert
- When Emacs starts, it looks for a saved desktop in the current
+ 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
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.
+@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.
To enter Tumme, type @kbd{M-x tumme}. It prompts for a directory;
specify one that has images files. This creates thumbnails for all
the images in that directory, and displays them all in the ``thumbnail
-buffer''. This takes a long time if the directory contains many image
+buffer.'' This takes a long time if the directory contains many image
files, and it asks for confirmation if the number of image files
exceeds @code{tumme-show-all-from-dir-max-files}.
(@code{tumme-display-thumbnail-original-image}) to display a sized
version of it in another window. This sizes the image to fit the
window. Use the arrow keys to move around in the buffer. For easy
-browing, type @kbd{SPC} (@code{tumme-display-next-thumbnail-original})
+browsing, type @kbd{SPC} (@code{tumme-display-next-thumbnail-original})
to advance and display the next image. Typing @kbd{DEL}
(@code{tumme-display-previous-thumbnail-original}) backs up to the
previous thumbnail and displays that instead.