mirror of https://github.com/Chizi123/.emacs.d.git

Chizi123
2018-11-18 76bbd07de7add0f9d13c6914f158d19630fe2f62
commit | author | age
5cb5f7 1 This is with-editor.info, produced by makeinfo version 6.5 from
C 2 with-editor.texi.
3
4      Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
5
6      You can redistribute this document and/or modify it under the terms
7      of the GNU General Public License as published by the Free Software
8      Foundation, either version 3 of the License, or (at your option)
9      any later version.
10
11      This document is distributed in the hope that it will be useful,
12      but WITHOUT ANY WARRANTY; without even the implied warranty of
13      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14      General Public License for more details.
15
16 INFO-DIR-SECTION Emacs
17 START-INFO-DIR-ENTRY
18 * With-Editor: (with-editor). Using the Emacsclient as $EDITOR.
19 END-INFO-DIR-ENTRY
20
21 
22 File: with-editor.info,  Node: Top,  Next: Using the With-Editor package,  Up: (dir)
23
24 With-Editor User Manual
25 ***********************
26
27 The library ‘with-editor’ makes it easy to use the Emacsclient as the
28 ‘$EDITOR’ of child processes, making sure they know how to call home.
29 For remote processes a substitute is provided, which communicates with
30 Emacs on standard output instead of using a socket as the Emacsclient
31 does.
32
33    This library was written because Magit has to be able to do the above
34 to allow the user to edit commit messages gracefully and to edit rebase
35 sequences, which wouldn’t be possible at all otherwise.
36
37    Because other packages can benefit from such functionality, this
38 library is made available as a separate package.  It also defines some
39 additional functionality which makes it useful even for end-users, who
40 don’t use Magit or another package which uses it internally.
41
42 This manual is for With-Editor version 2.8.0 (v2.8.0-2-g87c96b3+1).
43
44      Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
45
46      You can redistribute this document and/or modify it under the terms
47      of the GNU General Public License as published by the Free Software
48      Foundation, either version 3 of the License, or (at your option)
49      any later version.
50
51      This document is distributed in the hope that it will be useful,
52      but WITHOUT ANY WARRANTY; without even the implied warranty of
53      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
54      General Public License for more details.
55
56 * Menu:
57
58 * Using the With-Editor package::
59 * Using With-Editor as a library::
60 * Debugging::
61
62 — The Detailed Node Listing —
63
64 Using the With-Editor package
65
66 * Configuring With-Editor::
67 * Using With-Editor commands::
68
69
70 
71 File: with-editor.info,  Node: Using the With-Editor package,  Next: Using With-Editor as a library,  Prev: Top,  Up: Top
72
73 1 Using the With-Editor package
74 *******************************
75
76 The ‘With-Editor’ package is used internally by Magit when editing
77 commit messages and rebase sequences.  It also provides some commands
78 and features which are useful by themselves, even if you don’t use
79 Magit.
80
81    For information about using this library in you own package, see
82 *note Using With-Editor as a library::.
83
84 * Menu:
85
86 * Configuring With-Editor::
87 * Using With-Editor commands::
88
89 
90 File: with-editor.info,  Node: Configuring With-Editor,  Next: Using With-Editor commands,  Up: Using the With-Editor package
91
92 1.1 Configuring With-Editor
93 ===========================
94
95 With-Editor tries very hard to locate a suitable ‘emacsclient’
96 executable, so ideally you should never have to customize the option
97 ‘with-editor-emacsclient-executable’.  When it fails to do so, then the
98 most likely reason is that someone found yet another way to package
99 Emacs (most likely on macOS) without putting the executable on ‘$PATH’,
100 and we have to add another kludge to find it anyway.
101
102  -- User Option: with-editor-emacsclient-executable
103
104      The ‘emacsclient’ executable used as the editor by child process of
105      this Emacs instance.  By using this executable, child processes can
106      call home to their parent process.
107
108      This option is automatically set at startup by looking in
109      ‘exec-path’, and other places where the executable could be
110      installed, to find the ‘emacsclient’ executable most suitable for
111      the current Emacs instance.
112
113      You should *not* customize this option permanently.  If you have to
114      do it, then you should consider that a temporary kludge and inform
115      the Magit maintainer as described in *note Debugging::.
116
117      If With-Editor fails to find a suitable ‘emacsclient’ on you
118      system, then this should be fixed for all users at once, by
119      teaching ‘with-editor-locate-emacsclient’ how to do so on your
120      system and system like yours.  Doing it this way has the advantage,
121      that you won’t have do it again every time you update Emacs, and
122      that other users who have installed Emacs the same way as you have,
123      won’t have to go through the same trouble.
124
125      Note that there also is a nuclear option; setting this variable to
126      ‘nil’ causes the "sleeping editor" described below to be used even
127      for local child processes.  Obviously we don’t recommend that you
128      use this except in "emergencies", i.e.  before we had a change to
129      add a kludge appropriate for you setup.
130
131  -- Function: with-editor-locate-emacsclient
132
133      The function used to set the initial value of the option
134      ‘with-editor-emacsclient-executable’.  There’s a lot of voodoo
135      here.
136
137    The ‘emacsclient’ cannot be used when using Tramp to run a process on
138 a remote machine.  (Theoretically it could, but that would be hard to
139 setup, very fragile, and rather insecure).
140
141    With-Editor provides an alternative "editor" which can be used by
142 remote processes in much the same way as local processes use an
143 ‘emacsclient’ executable.  This alternative is known as the "sleeping
144 editor" because it is implemented as a shell script which sleeps until
145 it receives a signal.
146
147  -- User Option: with-editor-sleeping-editor
148
149      The sleeping editor is a shell script used as the editor of child
150      processes when the ‘emacsclient’ executable cannot be used.
151
152      This fallback is used for asynchronous process started inside the
153      macro ‘with-editor’, when the process runs on a remote machine or
154      for local processes when ‘with-editor-emacsclient-executable’ is
155      ‘nil’.
156
157      Where the latter uses a socket to communicate with Emacs’ server,
158      this substitute prints edit requests to its standard output on
159      which a process filter listens for such requests.  As such it is
160      not a complete substitute for a proper ‘emacsclient’, it can only
161      be used as ‘$EDITOR’ of child process of the current Emacs
162      instance.
163
164      Some shells do not execute traps immediately when waiting for a
165      child process, but by default we do use such a blocking child
166      process.
167
168      If you use such a shell (e.g.  ‘csh’ on FreeBSD, but not Debian),
169      then you have to edit this option.  You can either replace ‘sh’
170      with ‘bash’ (and install that), or you can use the older, less
171      performant implementation:
172
173           "sh -c '\
174           echo \"WITH-EDITOR: $$ OPEN $0 IN $(pwd)\"; \
175           trap \"exit 0\" USR1; \
176           trap \"exit 1\" USR2; \
177           while true; do sleep 1; done'"
178
179      Note that the unit seperator character () right after the file name
180      ($0) is required.
181
182      Also note that using this alternative implementation leads to a
183      delay of up to a second.  The delay can be shortened by replacing
184      ‘sleep 1’ with ‘sleep 0.01’, or if your implementation does not
185      support floats, then by using ‘nanosleep’ instead.
186
187 
188 File: with-editor.info,  Node: Using With-Editor commands,  Prev: Configuring With-Editor,  Up: Using the With-Editor package
189
190 1.2 Using With-Editor commands
191 ==============================
192
193 This section describes how to use the ‘with-editor’ library _outside_ of
194 Magit.  You don’t need to know any of this just to create commits using
195 Magit.
196
197    The commands ‘with-editor-async-shell-command’ and
198 ‘with-editor-shell-command’ are intended as drop in replacements for
199 ‘async-shell-command’ and ‘shell-command’.  They automatically export
200 ‘$EDITOR’ making sure the executed command uses the current Emacs
201 instance as "the editor".  With a prefix argument these commands prompt
202 for an alternative environment variable such as ‘$GIT_EDITOR’.
203
204  -- Command: with-editor-async-shell-command
205
206      This command is like ‘async-shell-command’, but it runs the shell
207      command with the current Emacs instance exported as ‘$EDITOR’.
208
209  -- Command: with-editor-shell-command
210
211      This command is like ‘shell-command’, but if the shell command ends
212      with ‘&’ and is therefore run asynchronously, then the current
213      Emacs instance is exported as ‘$EDITOR’.
214
215    To always use these variants add this to you init file:
216
217      (define-key (current-global-map)
218        [remap async-shell-command] 'with-editor-async-shell-command)
219      (define-key (current-global-map)
220        [remap shell-command] 'with-editor-shell-command)
221
222    Alternatively use the global ‘shell-command-with-editor-mode’.
223
224  -- Variable: shell-command-with-editor-mode
225
226      When this mode is active, then ‘$EDITOR’ is exported whenever
227      ultimately ‘shell-command’ is called to asynchronously run some
228      shell command.  This affects most variants of that command, whether
229      they are defined in Emacs or in some third-party package.
230
231    The command ‘with-editor-export-editor’ exports ‘$EDITOR’ or another
232 such environment variable in ‘shell-mode’, ‘term-mode’ and ‘eshell-mode’
233 buffers.  Use this Emacs command before executing a shell command which
234 needs the editor set, or always arrange for the current Emacs instance
235 to be used as editor by adding it to the appropriate mode hooks:
236
237      (add-hook 'shell-mode-hook  'with-editor-export-editor)
238      (add-hook 'term-exec-hook   'with-editor-export-editor)
239      (add-hook 'eshell-mode-hook 'with-editor-export-editor)
240
241    Some variants of this function exist; these two forms are equivalent:
242
243      (add-hook 'shell-mode-hook
244                (apply-partially 'with-editor-export-editor "GIT_EDITOR"))
245      (add-hook 'shell-mode-hook 'with-editor-export-git-editor)
246
247  -- Command: with-editor-export-editor
248
249      When invoked in a ‘shell-mode’, ‘term-mode’, or ‘eshell-mode’
250      buffer, this command teaches shell commands to use the current
251      Emacs instance as the editor, by exporting ‘$EDITOR’.
252
253  -- Command: with-editor-export-git-editor
254
255      This command is like ‘with-editor-export-editor’ but exports
256      ‘$GIT_EDITOR’.
257
258  -- Command: with-editor-export-hg-editor
259
260      This command is like ‘with-editor-export-editor’ but exports
261      ‘$HG_EDITOR’.
262
263 
264 File: with-editor.info,  Node: Using With-Editor as a library,  Next: Debugging,  Prev: Using the With-Editor package,  Up: Top
265
266 2 Using With-Editor as a library
267 ********************************
268
269 This section describes how to use the ‘with-editor’ library _outside_ of
270 Magit to teach another package how to have its child processes call
271 home, just like Magit does.  You don’t need to know any of this just to
272 create commits using Magit.  You can also ignore this if you use
273 ‘with-editor’ outside of Magit, but only as an end-user.
274
275    For information about interactive use and options that affect both
276 interactive and non-interactive use, see *note Using the With-Editor
277 package::.
278
279  -- Macro: with-editor &rest body
280
281      This macro arranges for the ‘emacsclient’ or the sleeping editor to
282      be used as the editor of child processes, effectively teaching them
283      to call home to the current Emacs instance when they require that
284      the user edits a file.
285
286      This is done by establishing a local binding for
287      ‘process-environment’ and changing the value of the ‘EDITOR’
288      environment variable in that scope.  This affects all
289      (asynchronous) processes started by forms (dynamically) inside
290      BODY.
291
292      If BODY begins with a literal string, then that variable is set
293      instead of ‘EDITOR’.
294
295  -- Macro: with-editor envvar &rest body
296
297      This macro is like ‘with-editor’ instead that the ENVVAR argument
298      is required and that it is evaluated at run-time.
299
300  -- Function: with-editor-set-process-filter process filter
301
302      This function is like ‘set-process-filter’ but ensures that adding
303      the new FILTER does not remove the ‘with-editor-process-filter’.
304      This is done by wrapping the two filter functions using a lambda,
305      which becomes the actual filter.  It calls
306      ‘with-editor-process-filter’ first, passing ‘t’ as
307      NO-STANDARD-FILTER.  Then it calls FILTER.
308
309 
310 File: with-editor.info,  Node: Debugging,  Prev: Using With-Editor as a library,  Up: Top
311
312 3 Debugging
313 ***********
314
315 With-Editor tries very hard to locate a suitable ‘emacsclient’
316 executable, and then sets option ‘with-editor-emacsclient-executable’
317 accordingly.  In very rare cases this fails.  When it does fail, then
318 the most likely reason is that someone found yet another way to package
319 Emacs (most likely on macOS) without putting the executable on ‘$PATH’,
320 and we have to add another kludge to find it anyway.
321
322    If you are having problems using ‘with-editor’, e.g.  you cannot
323 commit in Magit, then please open a new issue at
324 <https://github.com/magit/with-editor/issues> and provide information
325 about your Emacs installation.  Most importantly how did you install
326 Emacs and what is the output of ‘M-x with-editor-debug RET’.
327
328
329 
330 Tag Table:
331 Node: Top773
332 Node: Using the With-Editor package2535
333 Node: Configuring With-Editor3121
334 Node: Using With-Editor commands7670
335 Node: Using With-Editor as a library10865
336 Node: Debugging12828
337 
338 End Tag Table
339
340 
341 Local Variables:
342 coding: utf-8
343 End: