Re: Documenting universal-async-argument

[Michael Albinus <michael.albinus@gmx.de>]

[-- Attachment #1: Type: text/plain, Size: 376 bytes --]

Michael Albinus <michael.albinus@gmx.de> writes:

>> But feel free to find a different place, mine is just one opinion, and
>> not a very strong one in this case.
>
> I'm trying. But the essence of this thread is to find a good place; I
> didn't succeed so far.

I have prepared the following patch for the feature/tramp-thread-safe
branch. Comments?

Best regards, Michael.


[-- Attachment #2: Type: text/plain, Size: 2825 bytes --]

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 0753d6fb67..3ea775580a 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -26,6 +26,7 @@ Command Loop
 * Waiting::             Waiting for user input or elapsed time.
 * Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
 * Prefix Command Arguments::    How the commands to set prefix args work.
+* Prefix Commands::     A way to dispatch commands with an option.
 * Recursive Editing::   Entering a recursive edit,
                           and why you usually shouldn't.
 * Disabling Commands::  How the command loop handles disabled commands.
@@ -3299,6 +3300,39 @@ Prefix Command Arguments
 call this command yourself unless you know what you are doing.
 @end deffn
 
+@node Prefix Commands
+@section Prefix Commands
+@cindex prefix command
+
+  A @dfn{prefix command} is a command which precedes another command.
+It dispatches the @emph{next} command by toggling a controlling
+variable's value, which could be taken into account then by that next
+command.  Whether the following command cares about the controlling
+variable is up to that command.
+
+Emacs knows of two prefix commands, @code{universal-async-argument}
+(@pxref{Visiting,,, emacs, The GNU Emacs Manual}) and
+@code{universal-coding-system-argument} (@pxref{Text Coding,,, emacs,
+The GNU Emacs Manual}).
+
+@deffn Command universal-async-argument
+This prefix command indicates the next command to run asynchronously.
+It is up to that next command to decide, what asynchronously means, or
+to ignore the prefix command.
+@end deffn
+
+@defvar universal-async-argument
+This is the controlling variable toggled by the
+@code{universal-async-argument} command.  If a command supports
+asynchronous behavior, it should check, whether the value of this
+variable is non-@code{nil}.
+@end defvar
+
+@deffn Command universal-coding-system-argument
+It is a prefix command to determine the coding system to be applied
+for the next I/O command.  The coding system is read interactively.
+@end deffn
+
 @node Recursive Editing
 @section Recursive Editing
 @cindex recursive command loop
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 7ac9198bf8..30259343b6 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -762,6 +762,7 @@ Top
 * Waiting::             Waiting for user input or elapsed time.
 * Quitting::            How @kbd{C-g} works.  How to catch or defer quitting.
 * Prefix Command Arguments::    How the commands to set prefix args work.
+* Prefix Commands::     A way to dispatch commands with an option.
 * Recursive Editing::   Entering a recursive edit,
                           and why you usually shouldn't.
 * Disabling Commands::  How the command loop handles disabled commands.