comparison man/misc.texi @ 74494:ad8a70083559

(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.

74493:817f7407b88f

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 in 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.

@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}.)

@kindex C-x #
@findex server-edit
  Then, 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.

  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})

@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 visit 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,

* Invoking emacsclient:: Emacs client startup options.
@end menu

@node Invoking emacsclient,, Emacs Server, Emacs Server
@subsection Invoking @code{emacsclient}

  To run the @code{emacsclient} program, specify file names as arguments,
and optionally line numbers as well, like this:

@example

  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}} 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 @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.

If there is more than one Emacs server running, you can specify a
server name with the option @samp{-s @var{name}}.

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.

@node Printing, Sorting, Emacs Server, Top
@section Printing Hard Copies
@cindex hardcopy
@cindex printing

74494:ad8a70083559

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})

@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,

* 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

  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 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
@cindex hardcopy
@cindex printing