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

[Eli Zaretskii <eliz@gnu.org>]

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