341 lines
14 KiB
Plaintext
341 lines
14 KiB
Plaintext
This is with-editor.info, produced by makeinfo version 5.2 from
|
||
with-editor.texi.
|
||
|
||
The library ‘with-editor’ makes it easy to use the Emacsclient as the
|
||
‘$EDITOR’ of child processes, making sure they know how to call home.
|
||
For remote processes a substitute is provided, which communicates with
|
||
Emacs on standard output instead of using a socket as the Emacsclient
|
||
does.
|
||
|
||
This library was written because Magit has to be able to do the above
|
||
to allow the user to edit commit messages gracefully and to edit rebase
|
||
sequences, which wouldn’t be possible at all otherwise.
|
||
|
||
Because other packages can benefit from such functionality, this
|
||
library is made available as a separate package. It also defines some
|
||
additional functionality which makes it useful even for end-users, who
|
||
don’t use Magit or another package which uses it internally.
|
||
|
||
Copyright (C) 2015-2016 Jonas Bernoulli <jonas@bernoul.li>
|
||
|
||
You can redistribute this document and/or modify it under the terms
|
||
of the GNU General Public License as published by the Free Software
|
||
Foundation, either version 3 of the License, or (at your option)
|
||
any later version.
|
||
|
||
This document is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
General Public License for more details.
|
||
INFO-DIR-SECTION Emacs
|
||
START-INFO-DIR-ENTRY
|
||
* With-Editor: (with-editor). Using the Emacsclient as $EDITOR.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
|
||
File: with-editor.info, Node: Top, Next: Using the With-Editor package, Up: (dir)
|
||
|
||
With-Editor User Manual
|
||
***********************
|
||
|
||
The library ‘with-editor’ makes it easy to use the Emacsclient as the
|
||
‘$EDITOR’ of child processes, making sure they know how to call home.
|
||
For remote processes a substitute is provided, which communicates with
|
||
Emacs on standard output instead of using a socket as the Emacsclient
|
||
does.
|
||
|
||
This library was written because Magit has to be able to do the above
|
||
to allow the user to edit commit messages gracefully and to edit rebase
|
||
sequences, which wouldn’t be possible at all otherwise.
|
||
|
||
Because other packages can benefit from such functionality, this
|
||
library is made available as a separate package. It also defines some
|
||
additional functionality which makes it useful even for end-users, who
|
||
don’t use Magit or another package which uses it internally.
|
||
|
||
Copyright (C) 2015-2016 Jonas Bernoulli <jonas@bernoul.li>
|
||
|
||
You can redistribute this document and/or modify it under the terms
|
||
of the GNU General Public License as published by the Free Software
|
||
Foundation, either version 3 of the License, or (at your option)
|
||
any later version.
|
||
|
||
This document is distributed in the hope that it will be useful,
|
||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||
General Public License for more details.
|
||
|
||
* Menu:
|
||
|
||
* Using the With-Editor package::
|
||
* Using With-Editor as a library::
|
||
* Debugging::
|
||
|
||
— The Detailed Node Listing —
|
||
|
||
Using the With-Editor package
|
||
|
||
* Configuring With-Editor::
|
||
* Using With-Editor commands::
|
||
|
||
|
||
File: with-editor.info, Node: Using the With-Editor package, Next: Using With-Editor as a library, Prev: Top, Up: Top
|
||
|
||
1 Using the With-Editor package
|
||
*******************************
|
||
|
||
The ‘With-Editor’ package is used internally by Magit when editing
|
||
commit messages and rebase sequences. It also provides some commands
|
||
and features which are useful by themselves, even if you don’t use
|
||
Magit.
|
||
|
||
For information about using this library in you own package, see
|
||
*note Using With-Editor as a library: Using With-Editor as a library.
|
||
|
||
* Menu:
|
||
|
||
* Configuring With-Editor::
|
||
* Using With-Editor commands::
|
||
|
||
|
||
File: with-editor.info, Node: Configuring With-Editor, Next: Using With-Editor commands, Up: Using the With-Editor package
|
||
|
||
1.1 Configuring With-Editor
|
||
===========================
|
||
|
||
With-Editor tries very hard to locate a suitable emacsclient executable,
|
||
so ideally you should never have to customize the option
|
||
‘with-editor-emacsclient-executable’. When it fails to do so, then the
|
||
most likely reason is that someone found yet another way to package
|
||
Emacs (most likely on OS X) without putting the executable on ‘$PATH’,
|
||
and we have to add another kludge to find it anyway.
|
||
|
||
-- User Option: with-editor-emacsclient-executable
|
||
|
||
The emacsclient executable used as the editor by child process of
|
||
this Emacs instance. By using this executable, child processes can
|
||
call home to their parent process.
|
||
|
||
This option is automatically set at startup by looking in
|
||
‘exec-path’, and other places where the executable could be
|
||
installed, to find the emacsclient executable most suitable for the
|
||
current emacs instance.
|
||
|
||
You should *not* customize this option permanently. If you have to
|
||
do it, then you should consider that a temporary kludge and inform
|
||
the Magit maintainer as described in *note Debugging: Debugging.
|
||
|
||
If With-Editor fails to find a suitable emacsclient on you system,
|
||
then this should be fixed for all users at once, by teaching
|
||
‘with-editor-locate-emacsclient’ how to so on your system and
|
||
system like yours. Doing it this way has the advantage, that you
|
||
won’t have do it again every time you update Emacs, and that other
|
||
users who have installed Emacs the same way as you have, won’t have
|
||
to go through the same trouble.
|
||
|
||
Note that there also is a nuclear option; setting this variable to
|
||
‘nil’ causes the "sleeping editor" described below to be used even
|
||
for local child processes. Obviously we don’t recommend that you
|
||
use this except in "emergencies", i.e. before we had a change to
|
||
add a kludge appropriate for you setup.
|
||
|
||
-- Function: with-editor-locate-emacsclient
|
||
|
||
The function used to set the initial value of the option
|
||
‘with-editor-emacsclient-executable’. There’s a lot of voodoo
|
||
here.
|
||
|
||
The emacsclient cannot be used when using Tramp to run a process on a
|
||
remote machine. (Theoretically it could, but that would be hard to
|
||
setup, very fragile, and rather insecure).
|
||
|
||
With-Editor provides an alternative "editor" which can be used by
|
||
remote processes in much the same way as local processes use an
|
||
emacsclient executable. This alternative is known as the "sleeping
|
||
editor" because it is implemented as a shell script which sleeps until
|
||
it receives a signal.
|
||
|
||
-- User Option: with-editor-sleeping-editor
|
||
|
||
The sleeping editor is a shell script used as the editor of child
|
||
processes when the emacsclient executable cannot be used.
|
||
|
||
This fallback is used for asynchronous process started inside the
|
||
macro ‘with-editor’, when the process runs on a remote machine or
|
||
for local processes when ‘with-editor-emacsclient-executable’ is
|
||
‘nil’.
|
||
|
||
Where the latter uses a socket to communicate with Emacs’ server,
|
||
this substitute prints edit requests to its standard output on
|
||
which a process filter listens for such requests. As such it is
|
||
not a complete substitute for a proper Emacsclient, it can only be
|
||
used as ‘$EDITOR’ of child process of the current Emacs instance.
|
||
|
||
Some shells do not execute traps immediately when waiting for a
|
||
child process, but by default we do use such a blocking child
|
||
process.
|
||
|
||
If you use such a shell (e.g. ‘csh’ on FreeBSD, but not Debian),
|
||
then you have to edit this option. You can either replace ‘sh’
|
||
with ‘bash’ (and install that), or you can use the older, less
|
||
performant implementation:
|
||
|
||
"sh -c '\
|
||
echo \"WITH-EDITOR: $$ OPEN $0\"; \
|
||
trap \"exit 0\" USR1; \
|
||
trap \"exit 1\" USR2; \
|
||
while true; do sleep 1; done'"
|
||
|
||
This leads to a delay of up to a second. The delay can be
|
||
shortened by replacing ‘sleep 1’ with ‘sleep 0.01’, or if your
|
||
implementation does not support floats, then by using ‘nanosleep
|
||
0.01’ instead.
|
||
|
||
|
||
File: with-editor.info, Node: Using With-Editor commands, Prev: Configuring With-Editor, Up: Using the With-Editor package
|
||
|
||
1.2 Using With-Editor commands
|
||
==============================
|
||
|
||
This section describes how to use the ‘with-editor’ library _outside_ of
|
||
Magit. You don’t need to know any of this just to create commits using
|
||
Magit.
|
||
|
||
The commands ‘with-editor-async-shell-command’ and
|
||
‘with-editor-shell-command’ are intended as drop in replacements for
|
||
‘async-shell-command’ and ‘shell-command’. They automatically export
|
||
‘$EDITOR’ making sure the executed command uses the current Emacs
|
||
instance as "the editor". With a prefix argument these commands prompt
|
||
for an alternative environment variable such as ‘$GIT_EDITOR’.
|
||
|
||
-- Command: with-editor-async-shell-command
|
||
|
||
Like ‘async-shell-command’, but the command is run with the current
|
||
Emacs instance exported as ‘$EDITOR’.
|
||
|
||
-- Command: with-editor-shell-command
|
||
|
||
Like ‘async-shell-command’, but the command is run with the current
|
||
Emacs instance exported as ‘$EDITOR’. This only has an effect if
|
||
the command is run asynchronously, i.e. when the command ends with
|
||
‘&’.
|
||
|
||
To always use these variants add this to you init file:
|
||
|
||
(define-key (current-global-map)
|
||
[remap async-shell-command] 'with-editor-async-shell-command)
|
||
(define-key (current-global-map)
|
||
[remap shell-command] 'with-editor-shell-command)
|
||
|
||
Alternatively use the global ‘shell-command-with-editor-mode’.
|
||
|
||
-- Variable: shell-command-with-editor-mode
|
||
|
||
When this mode is active, then ‘$EDITOR’ is exported whenever
|
||
ultimately ‘shell-command’ is called to asynchronously run some
|
||
shell command. This affects most variants of that command, whether
|
||
they are defined in Emacs or in some third-party package.
|
||
|
||
The command ‘with-editor-export-editor’ exports ‘$EDITOR’ or another
|
||
such environment variable in ‘shell-mode’, ‘term-mode’ and ‘eshell-mode’
|
||
buffers. Use this Emacs command before executing a shell command which
|
||
needs the editor set, or always arrange for the current Emacs instance
|
||
to be used as editor by adding it to the appropriate mode hooks:
|
||
|
||
(add-hook 'shell-mode-hook 'with-editor-export-editor)
|
||
(add-hook 'term-exec-hook 'with-editor-export-editor)
|
||
(add-hook 'eshell-mode-hook 'with-editor-export-editor)
|
||
|
||
Some variants of this function exist; these two forms are equivalent:
|
||
|
||
(add-hook 'shell-mode-hook
|
||
(apply-partially 'with-editor-export-editor "GIT_EDITOR"))
|
||
(add-hook 'shell-mode-hook 'with-editor-export-git-editor)
|
||
|
||
-- Command: with-editor-export-editor
|
||
|
||
When invoked in a ‘shell-mode’, ‘term-mode’, or ‘eshell-mode’
|
||
buffer, this command teaches shell commands to use the current
|
||
Emacs instance as the editor, by exporting ‘$EDITOR’.
|
||
|
||
-- Command: with-editor-export-git-editor
|
||
|
||
Like ‘with-editor-export-editor’ but exports ‘$GIT_EDITOR’.
|
||
|
||
-- Command: with-editor-export-hg-editor
|
||
|
||
Like ‘with-editor-export-editor’ but exports ‘$HG_EDITOR’.
|
||
|
||
|
||
File: with-editor.info, Node: Using With-Editor as a library, Next: Debugging, Prev: Using the With-Editor package, Up: Top
|
||
|
||
2 Using With-Editor as a library
|
||
********************************
|
||
|
||
This section describes how to use the with-editor library _outside_ of
|
||
Magit to teach another package how to have its child processes call
|
||
home, just like Magit does. You don’t need to know any of this just to
|
||
create commits using Magit. You can also ignore this if you use
|
||
‘with-editor’ outside of Magit, but only as an end-user.
|
||
|
||
For information about interactive use and options which affect both
|
||
interactive and non-interactive use, see *note Using the With-Editor
|
||
package: Using the With-Editor package.
|
||
|
||
-- Macro: with-editor &rest body
|
||
|
||
This macro arranges for the emacsclient or the sleeping editor to
|
||
be used as the editor of child processes, effectively teaching them
|
||
to call home to the current emacs instance when they require that
|
||
the user edits a file.
|
||
|
||
This is essentially done by establishing a local binding for
|
||
‘process-environment’ and changing the value of the ‘$EDITOR’
|
||
environment variable. This affects all processes started by forms
|
||
inside BODY.
|
||
|
||
-- Function: with-editor-set-process-filter process filter
|
||
|
||
This function is like ‘set-process-filter’ but ensures that adding
|
||
the new FILTER does not remove the ‘with-editor-process-filter’.
|
||
This is done by wrapping the two filter functions using a lambda,
|
||
which becomes the actual filter. It calls
|
||
‘with-editor-process-filter’ first, passing ‘t’ as
|
||
NO-STANDARD-FILTER. Then it calls FILTER.
|
||
|
||
|
||
File: with-editor.info, Node: Debugging, Prev: Using With-Editor as a library, Up: Top
|
||
|
||
3 Debugging
|
||
***********
|
||
|
||
With-Editor tries very hard to locate a suitable emacsclient executable,
|
||
and then sets option ‘with-editor-emacsclient-executable’ accordingly.
|
||
In very rare cases this fails. When it does fail, then the most likely
|
||
reason is that someone found yet another way to package Emacs (most
|
||
likely on OS X) without putting the executable on ‘$PATH’, and we have
|
||
to add another kludge to find it anyway.
|
||
|
||
If you are having problems using ‘with-editor’, e.g. you cannot
|
||
commit in Magit, then please open a new issue at
|
||
<https://github.com/magit/with-editor/issues> and provide information
|
||
about your Emacs installation. Most importantly how did you install
|
||
Emacs and what is the output of ‘M-x with-editor-debug’?
|
||
|
||
|
||
|
||
Tag Table:
|
||
Node: Top1545
|
||
Node: Using the With-Editor package3236
|
||
Node: Configuring With-Editor3852
|
||
Node: Using With-Editor commands8201
|
||
Node: Using With-Editor as a library11364
|
||
Node: Debugging13036
|
||
|
||
End Tag Table
|
||
|
||
|
||
Local Variables:
|
||
coding: utf-8
|
||
End:
|