Commit d9d81805 authored by Eli Zaretskii's avatar Eli Zaretskii
Browse files

(Emacs Server): Improve wording. Don't mention the ``server program''.

Add a cross-reference to "Init File" node.
(Invoking emacsclient): Add index entries.  Document both short and long
versions of command-line options.  Document the -f option.
parent efe23027
2006-12-08 Eli Zaretskii <eliz@gnu.org>
* misc.texi (Emacs Server): Improve wording. Don't mention the
``server program''. Add a cross-reference to "Init File" node.
(Invoking emacsclient): Add index entries. Document both short and
long versions of command-line options. Document the -f option.
2006-12-08 Michael Olson <mwolson@gnu.org>
* erc.texi (Modules): Remove documentation for list module.
......
......@@ -1244,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
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
......@@ -1297,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
@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
......@@ -1335,6 +1343,7 @@ automatically when you finish with them.
@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:
......@@ -1363,37 +1372,57 @@ 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.)
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
@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.
@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
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 the TCP connection to the
server: the host where Emacs runs, the port where it listens for
@code{emacsclient} requests, and the authentication string to use for
the connection. @code{emacsclient} uses this information if it needs
to connect to the server via TCP. By default, this TCP configuration
file is placed 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 in addition attempts to find the file in
the @file{.emacs.d/server/} subdirectory of the directory pointed
to by the @env{APPDATA} environment variable, which is a user-specific
directory for application data files. This is similar to what Emacs
does on MS-Windows to search for the user's @file{.emacs} file.}
; you can
direct @code{emacsclient} to use a different file with the @samp{-f
@var{file}} or @samp{--server-file=@var{file}} option, or by defining
the @env{EMACS_SERVER_FILE} environment variable that points to the
non-default TCP configuration file.
@node Printing, Sorting, Emacs Server, Top
@section Printing Hard Copies
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment