bug#17779: 24.4.50; (elisp) `Using Interactive'

bug#17779: 24.4.50; (elisp) `Using Interactive'

[Drew Adams]

I wonder about the bullet "It may be a Lisp expression that is not a
string...".

1. The text for this does two things, which should perhaps be separated:
(a) it describes the general nature and use of such an expression, and
(b) it goes down a rabbit hole to talk about one particular gotcha.

Combining these in the same bullet, which is supposed to present the non-string Lisp sexp case, just confuses things - that's my guess.

2. Wrt that gotcha: Really?  I'm probably missing something here, since
this text has been in the manual for a long time.  But here's my take on
this gotcha. What am I missing?

> Providing point or the mark as an argument value is also common,
> but if you do this and read input (whether using the minibuffer
> or not), be sure to get the integer values of point or the mark
> after reading.

Why?  Why is after reading always (or typically) the appropriate time?

> The current buffer may be receiving subprocess output; if
> subprocess output arrives while the command is waiting for input,
> it could relocate point and the mark.

And?  Why is the location after reading more appropriate than before?
What does the input reading have to do, necessarily, with the timing of
the external process and its possible effect on the buffer text?

> Here's an example of what not to do:
>   (interactive
>    (list (region-beginning) (region-end)
>          (read-string "Foo: " nil 'my-history)))
> 
> Here's how to avoid the problem, by examining point and the mark
> after reading the keyboard input:
>   (interactive
>    (let ((string (read-string "Foo: " nil 'my-history)))
>      (list (region-beginning) (region-end) string)))

That does not make sense to me as a general guideline.  The appropriate
time for the interactive spec to record the region limits depends on
just what behavior one wants for the particular command.  I see no
reason to assume that one always (or typically) wants the limits to be
recorded after reading input instead of before.

If text modifications because of some external process are a concern,
then it is likely that the exact interaction between that process and
user input action needs to be taken into account for the particular
command definition.

IOW, I don't see why such a generalization is appropriate here.  What am
I missing?

[I would think it would be more typical (if any generalization is
appropriate here) for the command to make sure that such a process
finishes before checking the region limits, if the process can
change them.]


In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-08 on ODIEONE
Bzr revision: 117291 rgm@gnu.org-20140608234143-lxs3ijcc3exkcomq
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''

bug#17779: 24.4.50; (elisp) `Using Interactive'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> I wonder about the bullet "It may be a Lisp expression that is not a
> string...".
>
> 1. The text for this does two things, which should perhaps be separated:
> (a) it describes the general nature and use of such an expression, and
> (b) it goes down a rabbit hole to talk about one particular gotcha.
>
> Combining these in the same bullet, which is supposed to present the
> non-string Lisp sexp case, just confuses things - that's my guess.
>
> 2. Wrt that gotcha: Really?  I'm probably missing something here, since
> this text has been in the manual for a long time.  But here's my take on
> this gotcha. What am I missing?

(I've included the .texi below for reference.)

Yes, I think you're right -- the text starting with "Providing point or
the mark" until the end of the example seems like very confusing text to
include in an introduction to `interactive'.  The failure modes (if you
can call it that) are hyper-specific to a very obscure case, and (as
Drew says) what the user should do here depends on what the user wants.

So I think that bit should just be removed from the manual.

Any objections?

----

@item
It may be a Lisp expression that is not a string; then it should be a
form that is evaluated to get a list of arguments to pass to the
command.  Usually this form will call various functions to read input
from the user, most often through the minibuffer (@pxref{Minibuffers})
or directly from the keyboard (@pxref{Reading Input}).

Providing point or the mark as an argument value is also common, but
if you do this @emph{and} read input (whether using the minibuffer or
not), be sure to get the integer values of point or the mark after
reading.  The current buffer may be receiving subprocess output; if
subprocess output arrives while the command is waiting for input, it
could relocate point and the mark.

Here's an example of what @emph{not} to do:

@smallexample
(interactive
 (list (region-beginning) (region-end)
       (read-string "Foo: " nil 'my-history)))
@end smallexample

@noindent
Here's how to avoid the problem, by examining point and the mark after
reading the keyboard input:

@smallexample
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
@end smallexample

----

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#17779: 24.4.50; (elisp) `Using Interactive'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sun, 04 Aug 2019 14:41:55 +0200
> Cc: 17779@debbugs.gnu.org
> 
> Yes, I think you're right -- the text starting with "Providing point or
> the mark" until the end of the example seems like very confusing text to
> include in an introduction to `interactive'.

It isn't an introduction, it's a full description of how to use
'interactive'.  And I find nothing confusing about that part of the
text, I think that single paragraph with 2 examples to illustrate the
issue is quite appropriate here.

Please just leave this alone.  I object in principle to making
significant changes in the manuals based on hair-splitting arguments,
not in the least because someone will always come back later and claim
that the new text is worse, or less clear, or whatever.

At least in the docs, let's please avoid making changes for reasons
that are so minuscule that they need a magnifying glass to see.  We
should not waste our energy making "limit-cycle" kind of changes.

bug#17779: 24.4.50; (elisp) `Using Interactive'

[Drew Adams]

I don't even think it should say:

 "Usually this form will call various functions to read
  input from the user, most often through the minibuffer (*note
  Minibuffers::) or directly from the keyboard (*note Reading
  Input::)."

It can say that the form can read input etc. -
that's fine.  But I don't see the point of saying
"usually".  The point is that IF some argument
needs to be obtained by getting user input then
it that CAN be done by the form, e.g. reading from
the minibuffer etc.

But that's a nit.  ("Often" is better than "usually",
if you really want to stress that this is done often.)

> Yes, I think you're right -- the text starting with "Providing point or
> the mark" until the end of the example seems like very confusing text
> to
> include in an introduction to `interactive'.  The failure modes (if you
> can call it that) are hyper-specific to a very obscure case, and (as
> Drew says) what the user should do here depends on what the user wants.
> 
> So I think that bit should just be removed from the manual.
> 
> Any objections?

No objection from me, at least.  Thanks for
working on this.

bug#17779: 24.4.50; (elisp) `Using Interactive'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> It isn't an introduction, it's a full description of how to use
> 'interactive'.  And I find nothing confusing about that part of the
> text, I think that single paragraph with 2 examples to illustrate the
> issue is quite appropriate here.

I hadn't read that section before, and I just found it an odd thing to
talk about in that context -- as if there was something in particular
about code in the interactive spec that has to be extra careful about
buffer contents changing, when that's a general issue with points.

> Please just leave this alone.  I object in principle to making
> significant changes in the manuals based on hair-splitting arguments,
> not in the least because someone will always come back later and claim
> that the new text is worse, or less clear, or whatever.

Emacs has great documentation, but it (as everything else) can be
improved.  The argument you're making here seems to veer into the "well,
everything is subjective, so let's not even try" territory, which I know
you don't mean.  While going through these doc clarification bug
reports, I do close the ones I don't think are not worth doing and only
bring up the ones I think could benefit from some consideration.

But you think the text here is fine, so I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#17779: 24.4.50; (elisp) `Using Interactive'

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: drew.adams@oracle.com,  17779@debbugs.gnu.org
> Date: Mon, 05 Aug 2019 11:29:27 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > It isn't an introduction, it's a full description of how to use
> > 'interactive'.  And I find nothing confusing about that part of the
> > text, I think that single paragraph with 2 examples to illustrate the
> > issue is quite appropriate here.
> 
> I hadn't read that section before, and I just found it an odd thing to
> talk about in that context -- as if there was something in particular
> about code in the interactive spec that has to be extra careful about
> buffer contents changing, when that's a general issue with points.

Right, and that is exactly the point what the text tries to make.

> > Please just leave this alone.  I object in principle to making
> > significant changes in the manuals based on hair-splitting arguments,
> > not in the least because someone will always come back later and claim
> > that the new text is worse, or less clear, or whatever.
> 
> Emacs has great documentation, but it (as everything else) can be
> improved.  The argument you're making here seems to veer into the "well,
> everything is subjective, so let's not even try" territory, which I know
> you don't mean.

Indeed I didn't mean anything even close, and I'm sorry it seemed to
come across as something very different from my intent.  I
specifically mentioned "hair-splitting" and "minuscule" to make my
intent clear, but I guess this wasn't enough.

Our documentation does have places which need improvement -- places
where the text is unclear or confusing or presents the subject in an
order that is methodologically wrong, etc.  This particular text is
none of the above: it is very clear, describes real practical issues,
presents them in an order which makes sense, and is quite short, even
with the 2 examples and the surrounding small digression.  So my point
is that this is not one of the places where the manuals really do need
improvement, it's a place where different people might have different
opinions due to their personal preferences and experience.

> While going through these doc clarification bug reports, I do close
> the ones I don't think are not worth doing and only bring up the
> ones I think could benefit from some consideration.

I very much respect your opinions on those matters, and this case is a
very rare situation where we happen to disagree.

Thanks.

bug#17779: 24.4.50; (elisp) `Using Interactive'

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It can say that the form can read input etc. -
  > that's fine.  But I don't see the point of saying
  > "usually".

The point is to help the user understand the usage this feature
is intended for.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)