summaryrefslogtreecommitdiff
path: root/elpa/with-editor-20190715.2007/with-editor.info
diff options
context:
space:
mode:
authorblendoit <blendoit@gmail.com>2019-09-03 19:31:14 -0700
committerblendoit <blendoit@gmail.com>2019-09-03 19:31:14 -0700
commit9282e3afc2bcfbc2fe905a62ba5e03f7f019f46f (patch)
tree34b3df5ff601b78bd575a4992af77aa17db838f4 /elpa/with-editor-20190715.2007/with-editor.info
parent85f9213626a7230a3b5ca8d101c2e3181d06e07a (diff)
remove personal files
Diffstat (limited to 'elpa/with-editor-20190715.2007/with-editor.info')
-rw-r--r--elpa/with-editor-20190715.2007/with-editor.info343
1 files changed, 0 insertions, 343 deletions
diff --git a/elpa/with-editor-20190715.2007/with-editor.info b/elpa/with-editor-20190715.2007/with-editor.info
deleted file mode 100644
index 0addeba..0000000
--- a/elpa/with-editor-20190715.2007/with-editor.info
+++ /dev/null
@@ -1,343 +0,0 @@
-This is with-editor.info, produced by makeinfo version 6.5 from
-with-editor.texi.
-
- Copyright (C) 2015-2019 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.8.3.
-
- Copyright (C) 2015-2019 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 IN $(pwd)\"; \
- trap \"exit 0\" USR1; \
- trap \"exit 1\" USR2; \
- while true; do sleep 1; done'"
-
- Note that the unit seperator character () right after the file name
- ($0) is required.
-
- Also note that using this alternative implementation 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’ 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 ‘shell-command’, but if the shell command ends
- with ‘&’ and is therefore run asynchronously, then the current
- Emacs instance is exported as ‘$EDITOR’.
-
- 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 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.
-
- If BODY begins with a literal string, then that variable is set
- instead of ‘EDITOR’.
-
- -- Macro: with-editor envvar &rest body
-
- This macro is like ‘with-editor’ instead that the ENVVAR argument
- is required and that it is evaluated at run-time.
-
- -- 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: Top773
-Node: Using the With-Editor package2513
-Node: Configuring With-Editor3099
-Node: Using With-Editor commands7648
-Node: Using With-Editor as a library10843
-Node: Debugging12806
-
-End Tag Table
-
-
-Local Variables:
-coding: utf-8
-End:
Copyright 2019--2024 Marius PETER