[nongnu] elpa/with-editor 5bb0b8a 012/140: with-editor-sleeping-editor: document csh complications

[Jonas Bernoulli]

branch: elpa/with-editor
commit 5bb0b8ae05bc7c42779cbbf3f0368b5dd4b996b3
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    with-editor-sleeping-editor: document csh complications
    
    Closes #9.
---
 with-editor.el   | 22 +++++++++++++++++++++-
 with-editor.org  | 21 ++++++++++++++++++++-
 with-editor.texi | 21 ++++++++++++++++++++-
 3 files changed, 61 insertions(+), 3 deletions(-)

diff --git a/with-editor.el b/with-editor.el
index 665de74..423db88 100644
--- a/with-editor.el
+++ b/with-editor.el
@@ -184,7 +184,27 @@ 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."
+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'\"
+
+Note that 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'
+instead."
   :group 'with-editor
   :type 'string)
 
diff --git a/with-editor.org b/with-editor.org
index edf0134..7fb73fc 100644
--- a/with-editor.org
+++ b/with-editor.org
@@ -127,7 +127,26 @@ it receives a signal.
   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.
+  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:
+
+  #+BEGIN_SRC emacs-lisp
+    "sh -c '\
+    echo \"WITH-EDITOR: $$ OPEN $0\"; \
+    trap \"exit 0\" USR1; \
+    trap \"exit 1\" USR2; \
+    while true; do sleep 1; done'"
+  #+END_SRC
+
+  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.
 
 ** Using With-Editor commands
 
diff --git a/with-editor.texi b/with-editor.texi
index 66e8d64..93fd6b3 100644
--- a/with-editor.texi
+++ b/with-editor.texi
@@ -166,7 +166,26 @@ 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 @code{$EDITOR} of child process of the current Emacs instance.
 
-It is unlikely that you should ever have to customize this option.
+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. @code{csh} on FreeBSD, but not Debian), then
+you have to edit this option.  You can either replace @code{sh} with 
@code{bash}
+(and install that), or you can use the older, less performant
+implementation:
+
+@lisp
+"sh -c '\
+echo \"WITH-EDITOR: $$ OPEN $0\"; \
+trap \"exit 0\" USR1; \
+trap \"exit 1\" USR2; \
+while true; do sleep 1; done'"
+@end lisp
+
+This leads to a delay of up to a second.  The delay can be shortened
+by replacing @code{sleep 1} with @code{sleep 0.01}, or if your implementation 
does
+not support floats, then by using @code{nanosleep 0.01} instead.
 @end defopt
 
 @node Using With-Editor commands