Documenting universal-async-argument

Documenting universal-async-argument

[Michael Albinus]

Hi,

I'd like to document the prefix command universal-async-argument in the
Emacs Lisp manual. But I don't know where.

Section "Prefix Command Arguments" could be a place, but a prefix
command is not a prefix argument. Maybe just a new section after this,
and prior the section "Recursive Editing"? Don't know.

Any hint would be appreciated.

Thanks, and best regards, Michael.

Re: Documenting universal-async-argument

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Date: Tue, 07 Aug 2018 14:00:21 +0200
> 
> I'd like to document the prefix command universal-async-argument in the
> Emacs Lisp manual. But I don't know where.

This command is about using threads, right?  So how about documenting
it somewhere under "Threads"?

Re: Documenting universal-async-argument

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

>> I'd like to document the prefix command universal-async-argument in the
>> Emacs Lisp manual. But I don't know where.
>
> This command is about using threads, right?  So how about documenting
> it somewhere under "Threads"?

It is about threads just now. But it could be also for other
asynchronous command behavior, later on.

It is just a knob ("prefix command"), which tells the following command
"If you know something about asynchronity, and if you care, be informed
that the user wants you to run asynchronous".

Whatever this means.

Best regards, Michael.

Re: Documenting universal-async-argument

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: emacs-devel@gnu.org
> Date: Tue, 07 Aug 2018 18:06:29 +0200
> 
> > This command is about using threads, right?  So how about documenting
> > it somewhere under "Threads"?
> 
> It is about threads just now. But it could be also for other
> asynchronous command behavior, later on.

Do we really envision any other kind of asynchronicity in Emacs, any
time soon?  I'd be surprised.

> It is just a knob ("prefix command"), which tells the following command
> "If you know something about asynchronity, and if you care, be informed
> that the user wants you to run asynchronous".

universal-coding-system-argument is also "just a knob", and yet it is
described where coding-systems are.

But feel free to find a different place, mine is just one opinion, and
not a very strong one in this case.

Re: Documenting universal-async-argument

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

>> It is about threads just now. But it could be also for other
>> asynchronous command behavior, later on.

> Do we really envision any other kind of asynchronicity in Emacs, any
> time soon?  I'd be surprised.

Don't know. But, for example, any make-network-process based command
could also feel the challenge to use the "asynchronous" knob, w/o a
thread implementation.

I've took this general interpretation from your meessage
<838t5mt9wb.fsf@gnu.org>, where you have said

--8<---------------cut here---------------start------------->8---
I was actually thinking about something like universal-async-argument,
entirely unrelated to files etc.
--8<---------------cut here---------------end--------------->8---

You haven't restricted this command to files, so I took it as general as
possible. 

>> It is just a knob ("prefix command"), which tells the following command
>> "If you know something about asynchronity, and if you care, be informed
>> that the user wants you to run asynchronous".
>
> universal-coding-system-argument is also "just a knob", and yet it is
> described where coding-systems are.

Indeed, I was thinking of describing (or at least mentioning) that knob
as well in the new "prefix command" section.

> 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.

Best regards, Michael.

Re: Documenting universal-async-argument

[Michael Albinus]

[-- 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.

Re: Documenting universal-async-argument

[Eli Zaretskii]

> From: Michael Albinus <michael.albinus@gmx.de>
> Cc: emacs-devel@gnu.org
> Date: Fri, 17 Aug 2018 17:02:02 +0200
> 
> +@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
                                          ^
This comma should be removed.

> +@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
                                         ^
And this one.

> +@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.

"This prefix command determines the coding-system to be used by the
next I/O command."

Thanks.

Re: Documenting universal-async-argument

[Michael Albinus]

Eli Zaretskii <eliz@gnu.org> writes:

>> +@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
>                                           ^
> This comma should be removed.
>
>> +@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
>                                          ^
> And this one.
>
>> +@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.
>
> "This prefix command determines the coding-system to be used by the
> next I/O command."

Nobody else did comment, so I have pushed this to the
feature/tramp-thread-safe branch with the proposed changes.

> Thanks.

Best regards, Michael.