reincarnation release

`with-editor.el' is no longer part of the Magit repository but its
karma is good and so it is reborn as a repository of its own.

To help it remember its past life do this:

  git remote add magit https://github.com/magit/magit.git
  git config remote.magit.tagopt --no-tags
  git fetch magit
  git replace --graft <this> f78f1cd33692e8b544d883d66400ab5c752663f2

See the git-replace(1) manpage for more information.

While they were still part of the Magit repository `with-editor.el'
and `with-editor.org' were edited by the following people:

    88  Jonas Bernoulli
     4  Noam Postavsky
     2  Rémi Vanicat
     1  Barak A. Pearlmutter
     1  Lele Gaifax
     1  Philippe Vaucher

1 files changed, 258 insertions, 0 deletions

diff --git a/with-editor.org b/with-editor.org
new file mode 100644
index 0000000..73c11f7
--- /dev/null
+++ b/with-editor.org
@@ -0,0 +1,258 @@
+#+TITLE: With-Editor User Manual
+#+AUTHOR: Jonas Bernoulli
+#+EMAIL: jonas@bernoul.li
+#+DATE: 2015-2016
+#+LANGUAGE: en
+
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: With-Editor: (with-editor).
+#+TEXINFO_DIR_DESC: Using the Emacsclient as $EDITOR
+#+SUBTITLE: for version 2.5
+
+#+OPTIONS: H:4 num:3 toc:2
+
+* Copying
+:PROPERTIES:
+:COPYING:    t
+:END:
+
+#+BEGIN_TEXINFO
+@ifnottex
+The library @code{with-editor} makes it easy to use the Emacsclient as
+the @code{$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.
+@end ifnottex
+
+@quotation
+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.
+@end quotation
+#+END_TEXINFO
+
+* 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
+[[*Using With-Editor as a library]].
+
+** 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 [[*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.
+
+  It is unlikely that you should ever have to customize this option.
+
+** 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:
+
+#+BEGIN_SRC emacs-lisp
+  (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)
+#+END_SRC
+
+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:
+
+#+BEGIN_SRC emacs-lisp
+  (add-hook 'shell-mode-hook  'with-editor-export-editor)
+  (add-hook 'term-mode-hook   'with-editor-export-editor)
+  (add-hook 'eshell-mode-hook 'with-editor-export-editor)
+#+END_SRC
+
+Some variants of this function exist; these two forms are equivalent:
+
+#+BEGIN_SRC emacs-lisp
+  (add-hook 'shell-mode-hook
+            (apply-partially 'with-editor-export-editor "GIT_EDITOR"))
+  (add-hook 'shell-mode-hook 'with-editor-export-git-editor)
+#+END_SRC
+
+- 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~.
+
+* 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 [[*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.
+
+* 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/magit/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~?
+
+#  LocalWords:  Emacsclient LocalWords Magit async emacs emacsclient
+#  LocalWords:  hg init rebase startup