Subject: bug#67185: Small bug in the Introduction to Elisp manual

From: Ryan Hodges <[email-masked]>
Date: Tue, 14 Nov 2023 15:14:53 -0800

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