From: Michael Albinus <michael.albinus@gmx.de>
Date: Sat, 25 Aug 2018 11:10:10 +0000 (+0200)
Subject: Document prefix commands
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a692095fd8cde03dc7d863c9ac9d85bac181e616;p=emacs.git

Document prefix commands

* doc/lispref/commands.texi (Prefix Commands): New node.
(Command Loop):
* doc/lispref/elisp.texi (Top): Add Prefix Commands menue entry.
---

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 0753d6fb67c..6cbda8f4fd1 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -26,6 +26,7 @@ are done, and the subroutines that allow Lisp programs to do them.
 * 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 @@ command; its value is negated to form the new prefix argument.  Don't
 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
+This prefix command determines the coding system to be used by the
+next I/O command.
+@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 7ac9198bf84..30259343b64 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -762,6 +762,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.