Subject: bug#67185: closed (Re: bug#67185: Small bug in the Introduction to Elisp manual)

From: [email-masked] (GNU bug Tracking System)
Date: Sun, 19 Nov 2023 10:17:01 +0000

Your bug report

#67185: Small bug in the Introduction to Elisp manual

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
67185: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=67185
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#67185: Small bug in the Introduction to Elisp manual
From: Eli Zaretskii <[email-masked]>
To: [email-masked]
Cc: [email-masked], [email-masked]
Date: Sun, 19 Nov 2023 12:16:13 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Richard Stallman <[email-masked]>
> Cc: [email-masked], [email-masked]
> Date: Sat, 18 Nov 2023 22:40:43 -0500
> 
>   > That manual uses "converse" and "conversely" about half a dozen times:
>   > are all of them incorrect, and actually mean "opposite" or maybe "by
>   > contrast"?
> 
> I checked these, and I think they are correct.  Each one is about reversing
> the direction of some relation, and "converse" means that/
> 
>     > The @code{kill-region} function definition also has an @code{unless}
>     > macro; it is the converse of @code{when}.
> 
> That should say "opposite".  It's opposite because in the situation
> where `when' runs its body, `unless' does not run its body.
> 
>                                                  The @code{unless} macro is
>     > an @code{if} without a then clause
> 
> The point is valid if understood in a figurative sense -- so the
> words need to indicate it is meant figuratively, not literally.  How
> to do that?  Maybe this:
> 
>                                                  The @code{unless} macro is
>      like an @code{if} except that it has no then-clause, and it supplies
>      an implicit @code{nil} for that.

Thanks, I fixed these two places as you suggested, and I'm therefore
closing this bug.

Subject: Small bug in the Introduction to Elisp manual
From: Ryan Hodges <[email-masked]>
To: [email-masked]
Date: Tue, 14 Nov 2023 15:14:53 -0800
List-Id: <debbugs-submit.debbugs.gnu.org>

In section '8.2.2 Lisp macro' it says,

"The ‘kill-region’ function definition also has an ‘unless’ macro; it
is the converse of ‘when’.  The ‘unless’ macro is an ‘if’ without a
then clause"

Instead of saying "converse of 'when'" it should say "inverse of 'when'."
Also, that statement about 'unless' being an 'if' without a 'then' clause
tripped me up. I thought you were trying to say that the 'unless' form
didn't have a then clause, which isn't correct.  Then I thought the point
you were really trying to make was that the unless form, like when, doesn't
have an 'else' clause.

Now that I've read the corresponding section in the reference manual I know
what you mean.   I think we should borrow the examples from the reference
manual  to make it clear and also emphasize that 'unless' is a convenient
mechanism for evaluating multiple statements when a condition is not true.

Maybe the text should be:

"The kill-region function definition also has an 'unless' macro. It is the
inverse of 'when'. The form,

(unless CONDITION A B C)

is equivalent to the form

(when (not (CONDITION)) A B C)

The 'unless' form is ideal in situations when multiple expressions should
be evaluated when a condition is not true. The 'unless' macro can also be
viewed as an 'if' which does nothing in the 'then' clause but evaluates one
or more statements in the 'else' clause.  In particular,

(unless CONDITION A B C)

is equivalent to the form,

(if CONDITION nil A B C)

In other words, if CONDITION is true, the form does nothing.  Otherwise,
when CONDITION is false, the form evaluates 'A B C'.

If you approve of the text or provide me more accurate phrasing, I'll
gladly submit a patch.  I also understand if you think I'm being a little
too verbose.

Regards,
Ryan Hodges