diff options
Diffstat (limited to 'configs/shared/emacs/.emacs.d/elpa/with-editor-20180726.2044/with-editor.info')
| -rw-r--r-- | configs/shared/emacs/.emacs.d/elpa/with-editor-20180726.2044/with-editor.info | 331 |
1 files changed, 0 insertions, 331 deletions
diff --git a/configs/shared/emacs/.emacs.d/elpa/with-editor-20180726.2044/with-editor.info b/configs/shared/emacs/.emacs.d/elpa/with-editor-20180726.2044/with-editor.info deleted file mode 100644 index 62bd9c9c8cc7..000000000000 --- a/configs/shared/emacs/.emacs.d/elpa/with-editor-20180726.2044/with-editor.info +++ /dev/null @@ -1,331 +0,0 @@ -This is with-editor.info, produced by makeinfo version 6.5 from -with-editor.texi. - - Copyright (C) 2015-2018 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. - -This manual is for With-Editor version 2.7.4. - - Copyright (C) 2015-2018 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::. - -* 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 macOS) 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::. - - 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 do 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 - - This command is like ‘async-shell-command’, but it runs the shell - command with the current Emacs instance exported as ‘$EDITOR’. - - -- Command: with-editor-shell-command - - This command is like ‘async-shell-command’, but it runs the shell - command with the current Emacs instance exported as ‘$EDITOR’. - This only has an effect if the shell 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 - - This command is like ‘with-editor-export-editor’ but exports - ‘$GIT_EDITOR’. - - -- Command: with-editor-export-hg-editor - - This command is 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 that affect both -interactive and non-interactive use, see *note 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 in that scope. This affects all asynchronous - processes started by forms (dynamically) 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 macOS) 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 RET’. - - - -Tag Table: -Node: Top772 -Node: Using the With-Editor package2512 -Node: Configuring With-Editor3098 -Node: Using With-Editor commands7495 -Node: Using With-Editor as a library10758 -Node: Debugging12454 - -End Tag Table - - -Local Variables: -coding: utf-8 -End: |