(User Interface, Basic Types): Document need to put some

[gnu-emacs] / man / misc.texi

diff --git a/man/misc.texi b/man/misc.texi
index 33c85a9fc8b0d4f44563a76c1dfd0eaff71eaaa9..bfe86af09f46f4a463b90b7ff641db38964fa743 100644 (file)
--- a/man/misc.texi
+++ b/man/misc.texi
@@ -1,6 +1,6 @@
 @c This is part of the Emacs manual.
 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
 @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
 @c See file emacs.texi for copying conditions.
 @iftex
 @chapter Miscellaneous Commands


@@ -478,7 +478,8 @@ either or both of these default initializations.
 @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_@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
 
   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


@@ -486,11 +487,16 @@ also change the coding system for a running subshell by typing
 @kbd{C-x @key{RET} p} in the shell buffer.  @xref{Communication
 Coding}.
 
 @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
 @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
 
 @node Shell Mode
 @subsection Shell Mode


@@ -977,8 +983,8 @@ 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
 
 @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}.
 
 text as possible.  (This mimics the scrolling behavior of most
 terminals.)  The default is @code{t}.
 


@@ -1238,28 +1244,36 @@ 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
 @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
 
   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
 
 @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
 
 @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
 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
 
   When you've finished editing that buffer, type @kbd{C-x #}
 (@code{server-edit}).  This saves the file and sends a message back to


@@ -1291,8 +1305,8 @@ kills it if the file name matches the regular expression
 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
 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
 
   While @code{mail} or another application is waiting for
 @code{emacsclient} to finish, @code{emacsclient} does not read terminal


@@ -1329,6 +1343,7 @@ automatically when you finish with them.
 
 @node Invoking emacsclient,, Emacs Server, Emacs Server
 @subsection Invoking @code{emacsclient}
 
 @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:
 
   To run the @code{emacsclient} program, specify file names as arguments,
 and optionally line numbers as well, like this:


@@ -1357,37 +1372,52 @@ a client buffer, the next client buffer is automatically selected.
 @code{emacsclient}, then it returns immediately.  (You can take as
 long as you like to edit the files in Emacs.)
 
 @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}} 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 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
 
 @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.
 
 The environment variable @env{ALTERNATE_EDITOR} has the same effect, with
 the value of the @samp{--alternate-editor} option taking precedence.
 

-@pindex emacs.bash
-  Alternatively, the file @file{etc/emacs.bash} defines a bash
-function which will communicate with a running Emacs server, or start
-one if none exists.
-

 If you use several displays, you can tell Emacs on which display to
 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
 
 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
 
 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
 
 @node Printing, Sorting, Emacs Server, Top
 @section Printing Hard Copies


@@ -1998,11 +2028,11 @@ 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
 @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 and its restoring 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:
+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)
 
 @example
 (desktop-save-mode 1)