[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/with-editor ee41302 029/140: manual: minor improvements an
From: |
Jonas Bernoulli |
Subject: |
[nongnu] elpa/with-editor ee41302 029/140: manual: minor improvements and typo fixes |
Date: |
Fri, 6 Aug 2021 12:51:14 -0400 (EDT) |
branch: elpa/with-editor
commit ee41302fea917eb113182bc1eb8d44de882233f8
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>
manual: minor improvements and typo fixes
---
with-editor.org | 67 +++++++++++++++++++++++++++++---------------------------
with-editor.texi | 62 ++++++++++++++++++++++++++-------------------------
2 files changed, 67 insertions(+), 62 deletions(-)
diff --git a/with-editor.org b/with-editor.org
index 660f0d3..6c2d844 100644
--- a/with-editor.org
+++ b/with-editor.org
@@ -62,35 +62,35 @@ For information about using this library in you own
package, see
** Configuring With-Editor
-With-Editor tries very hard to locate a suitable emacsclient
+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~,
+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
+ 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
+ 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,
+ 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.
+ ~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
@@ -103,20 +103,20 @@ and we have to add another kludge to find it anyway.
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
+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
+~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.
+ 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
@@ -125,7 +125,7 @@ it receives a signal.
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
+ 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
@@ -164,15 +164,15 @@ 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~.
+ 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
- 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 ~&~.
+ 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:
@@ -221,11 +221,13 @@ Some variants of this function exist; these two forms are
equivalent:
- Command: with-editor-export-git-editor
- Like ~with-editor-export-editor~ but exports ~$GIT_EDITOR~.
+ This command is like ~with-editor-export-editor~ but exports
+ ~$GIT_EDITOR~.
- Command: with-editor-export-hg-editor
- Like ~with-editor-export-editor~ but exports ~$HG_EDITOR~.
+ This command is like ~with-editor-export-editor~ but exports
+ ~$HG_EDITOR~.
* Using With-Editor as a library
@@ -235,21 +237,21 @@ 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
+For information about interactive use and options that 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
+ 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
+ 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.
+ environment variable in that scope. This affects all asynchronous
+ processes started by forms (dynamically) inside BODY.
- Function: with-editor-set-process-filter process filter
@@ -261,21 +263,22 @@ package]].
* Debugging
-With-Editor tries very hard to locate a suitable emacsclient
+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
+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~?
+Emacs and what is the output of ~M-x with-editor-debug RET~.
-# LocalWords: Emacsclient LocalWords Magit async emacs emacsclient
-# LocalWords: hg init rebase startup
+# LocalWords: LocalWords
+# LocalWords: Magit Emacs emacsclient FreeBSD macOS texinfo
+# LocalWords: async eval hg init performant rebase startup
# Local Variables:
# eval: (require 'ox-texinfo+ nil t)
diff --git a/with-editor.texi b/with-editor.texi
index 9092c3d..50bc8e8 100644
--- a/with-editor.texi
+++ b/with-editor.texi
@@ -98,35 +98,35 @@ For information about using this library in you own
package, see
@node Configuring With-Editor
@section Configuring With-Editor
-With-Editor tries very hard to locate a suitable emacsclient
+With-Editor tries very hard to locate a suitable @code{emacsclient}
executable, so ideally you should never have to customize the option
@code{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 @code{$PATH},
+Emacs (most likely on macOS) without putting the executable on @code{$PATH},
and we have to add another kludge to find it anyway.
@defopt with-editor-emacsclient-executable
-The emacsclient executable used as the editor by child process of
+The @code{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 @code{exec-path},
and other places where the executable could be installed, to find
-the emacsclient executable most suitable for the current emacs
+the @code{emacsclient} executable most suitable for the current Emacs
instance.
You should @strong{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 @ref{Debugging,Debugging}.
-If With-Editor fails to find a suitable emacsclient on you system,
+If With-Editor fails to find a suitable @code{emacsclient} on you system,
then this should be fixed for all users at once, by teaching
-@code{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.
+@code{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
@code{nil} causes the "sleeping editor" described below to be used even for
@@ -141,20 +141,20 @@ The function used to set the initial value of the option
@code{with-editor-emacsclient-executable}. There's a lot of voodoo here.
@end defun
-The emacsclient cannot be used when using Tramp to run a process on a
+The @code{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
+@code{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.
@defopt 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.
+processes when the @code{emacsclient} executable cannot be used.
This fallback is used for asynchronous process started inside the
macro @code{with-editor}, when the process runs on a remote machine or for
@@ -163,7 +163,7 @@ local processes when
@code{with-editor-emacsclient-executable} is @code{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
+not a complete substitute for a proper @code{emacsclient}, it can only
be used as @code{$EDITOR} of child process of the current Emacs instance.
Some shells do not execute traps immediately when waiting for a
@@ -205,17 +205,17 @@ prompt for an alternative environment variable such as
@code{$GIT_EDITOR}.
@cindex with-editor-async-shell-command
@deffn Command with-editor-async-shell-command
-Like @code{async-shell-command}, but the command is run with the current
-Emacs instance exported as @code{$EDITOR}.
+This command is like @code{async-shell-command}, but it runs the shell
+command with the current Emacs instance exported as @code{$EDITOR}.
@end deffn
@cindex with-editor-shell-command
@deffn Command with-editor-shell-command
-Like @code{async-shell-command}, but the command is run with the current
-Emacs instance exported as @code{$EDITOR}. This only has an effect if
-the command is run asynchronously, i.e. when the command ends
-with @code{&}.
+This command is like @code{async-shell-command}, but it runs the shell
+command with the current Emacs instance exported as @code{$EDITOR}. This
+only has an effect if the shell command is run asynchronously,
+i.e. when the command ends with @code{&}.
@end deffn
To always use these variants add this to you init file:
@@ -269,13 +269,15 @@ the editor, by exporting @code{$EDITOR}.
@cindex with-editor-export-git-editor
@deffn Command with-editor-export-git-editor
-Like @code{with-editor-export-editor} but exports @code{$GIT_EDITOR}.
+This command is like @code{with-editor-export-editor} but exports
+@code{$GIT_EDITOR}.
@end deffn
@cindex with-editor-export-hg-editor
@deffn Command with-editor-export-hg-editor
-Like @code{with-editor-export-editor} but exports @code{$HG_EDITOR}.
+This command is like @code{with-editor-export-editor} but exports
+@code{$HG_EDITOR}.
@end deffn
@node Using With-Editor as a library
@@ -287,20 +289,20 @@ 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
@code{with-editor} outside of Magit, but only as an end-user.
-For information about interactive use and options which affect both
+For information about interactive use and options that affect both
interactive and non-interactive use, see @ref{Using the With-Editor
package,Using the With-Editor package}.
@defmac with-editor &rest body
-This macro arranges for the emacsclient or the sleeping editor to be
+This macro arranges for the @code{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
+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
@code{process-environment} and changing the value of the @code{$EDITOR}
-environment variable. This affects all processes started by forms
-inside BODY.
+environment variable in that scope. This affects all asynchronous
+processes started by forms (dynamically) inside BODY.
@end defmac
@defun with-editor-set-process-filter process filter
@@ -315,17 +317,17 @@ first, passing @code{t} as NO-STANDARD-FILTER. Then it
calls FILTER.
@node Debugging
@chapter Debugging
-With-Editor tries very hard to locate a suitable emacsclient
+With-Editor tries very hard to locate a suitable @code{emacsclient}
executable, and then sets option @code{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
+package Emacs (most likely on macOS) without putting the executable on
@code{$PATH}, and we have to add another kludge to find it anyway.
If you are having problems using @code{with-editor}, e.g. you cannot commit
in Magit, then please open a new issue at
@uref{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 @code{M-x with-editor-debug}?
+Emacs and what is the output of @code{M-x with-editor-debug RET}.
@bye
- [nongnu] elpa/with-editor d28d074 008/140: regenerate manual after updating org and ox-texinfo+, (continued)
- [nongnu] elpa/with-editor d28d074 008/140: regenerate manual after updating org and ox-texinfo+, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor f602113 014/140: make: add bump-versions target, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor aaaeb98 022/140: prefer debianized binary name, if available, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor fb1e10a 030/140: Ignore /dir, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 1126035 004/140: Add remaps for common evil commands, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 5bb0b8a 012/140: with-editor-sleeping-editor: document csh complications, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 15b2565 013/140: AUTHORS.md: update list of contributors, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 19201be 021/140: with-editor-locate-emacsclient-1: look for yet another suffix, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor c05420c 020/140: don't use pcase-dolist, not all supported Emacsen have it, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor de4022e 018/140: stop directing users to the issue tracker of magit, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor ee41302 029/140: manual: minor improvements and typo fixes,
Jonas Bernoulli <=
- [nongnu] elpa/with-editor 2248a63 031/140: bump version, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor eb00831 033/140: with-editor-debug: add link to manual to doc-string, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 9fc0477 040/140: with-editor-output-filter: don't use tramp-make-tramp-file-name, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor ae405e9 052/140: with-editor-export-editor: remove unnecessary leftovers, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 216ee34 056/140: Build on Travis, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor b37d94b 035/140: with-editor-debug: fix old reference to magit in output, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 706c8ce 011/140: instruct users to use term-exec-hook, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 07bb67b 010/140: remove with-editor-export-editor from hook for shell-command, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 6f41998 017/140: with-editor-export-editor: fix doc-string, Jonas Bernoulli, 2021/08/06
- [nongnu] elpa/with-editor 0a8d9ce 039/140: manual: set version in Org source, Jonas Bernoulli, 2021/08/06