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

From: Eli Zaretskii <[email-masked]>
Date: Wed, 15 Nov 2023 14:18:06 +0200

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

I'm not a native English speaker, but "converse" sounds correct to me
in this context.

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

No, it says it doesn't have "then", i.e. it only have the "else" part.
Which sounds fine to me.

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

This manual was written by a person whose command of the English
language and whose methodological skill are exceptional.  So I'm
adding Richard to this discussion, and ask him to judge this text,
and whether it needs to be improved and how.

Thanks.