GNU bug report logs -
#67185
Small bug in the Introduction to Elisp manual
Previous Next
Reported by: Ryan Hodges <rphodges <at> gmail.com>
Date: Wed, 15 Nov 2023 01:58:03 UTC
Severity: normal
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 67185 in the body.
You can then email your comments to 67185 AT debbugs.gnu.org in the normal way.
Toggle the display of automated, internal messages from the tracker.
Report forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Wed, 15 Nov 2023 01:58:03 GMT)
Full text and
rfc822 format available.
Acknowledgement sent
to
Ryan Hodges <rphodges <at> gmail.com>:
New bug report received and forwarded. Copy sent to
bug-gnu-emacs <at> gnu.org.
(Wed, 15 Nov 2023 01:58:03 GMT)
Full text and
rfc822 format available.
Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
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
[Message part 2 (text/html, inline)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Wed, 15 Nov 2023 16:29:07 GMT)
Full text and
rfc822 format available.
Message #8 received at 67185 <at> debbugs.gnu.org (full text, mbox):
> From: Ryan Hodges <rphodges <at> gmail.com>
> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Wed, 15 Nov 2023 19:34:01 GMT)
Full text and
rfc822 format available.
Message #11 received at 67185 <at> debbugs.gnu.org (full text, mbox):
[Please use Reply All to reply, so that everyone is CC'ed.]
> From: Ryan Hodges <rphodges <at> gmail.com>
> Date: Wed, 15 Nov 2023 09:58:11 -0800
>
> On Wed, Nov 15, 2023 at 4:18 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
>
> > From: Ryan Hodges <rphodges <at> gmail.com>
> > 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.
>
> 'converse' means to reverse the order of.
Not necessarily, at least not according to the dictionaries I see. For example
(https://www.collinsdictionary.com/us/dictionary/english/converse):
The converse of a statement is its opposite or reverse.
Or (https://dictionary.cambridge.org/dictionary/english/converse):
the opposite:
. In the US, you drive on the right-hand side of the road, but in the UK the converse applies.
. However, the converse of this theory may also be true.
> No, it says it doesn't have "then", i.e. it only have the "else" part.
> Which sounds fine to me.
>
> Earlier in the document, 'when' is described as an 'if' statement without an 'else' clause. That makes
> sense to me. The 'else' clause is completely optional. i.e the 'if' form below does not have an 'else'
>
> (if (> 5 4) 'true)
>
> In this section of the document we are describing an 'if' without a 'then'. That didn't make sense to me
> because the 'then' clause is a mandatory argument. It can be 'nil' but it's still mandatory.
AFAIU, the text attempts to explain 'when' and 'unless' in terms if
'if', and it doesn't try to be rigorously correct, but rather to be
intuitively understandable by people who may not be programmers or
have a mathematical background. So "if without then" might not make
sense to someone who has the "if" syntax burnt into his/her muscle
memory, but it does make sense if you consider that "if" has a "then"
block and an "else" block, and "unless" executes the "else" block of
the condition.
So this is why I asked Richard to review this text and your comments.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Wed, 15 Nov 2023 20:19:01 GMT)
Full text and
rfc822 format available.
Message #14 received at 67185 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Eli,
Thanks for the reply. I can see where you're going with the word
'converse'. I'm not hung up on it but I think it could use a little
clarification on what we mean by "opposite of 'when'".
If you decide the manual warrants a tweak and you want me to take a crack
at it, let me know. Otherwise, I appreciate your time.
Cheers,
Ryan Hodges
On Wed, Nov 15, 2023 at 11:33 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
> [Please use Reply All to reply, so that everyone is CC'ed.]
>
> > From: Ryan Hodges <rphodges <at> gmail.com>
> > Date: Wed, 15 Nov 2023 09:58:11 -0800
> >
> > On Wed, Nov 15, 2023 at 4:18 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
> >
> > > From: Ryan Hodges <rphodges <at> gmail.com>
> > > 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.
> >
> > 'converse' means to reverse the order of.
>
> Not necessarily, at least not according to the dictionaries I see. For
> example
> (https://www.collinsdictionary.com/us/dictionary/english/converse):
>
> The converse of a statement is its opposite or reverse.
>
> Or (https://dictionary.cambridge.org/dictionary/english/converse):
>
> the opposite:
> . In the US, you drive on the right-hand side of the road, but in the
> UK the converse applies.
> . However, the converse of this theory may also be true.
>
> > No, it says it doesn't have "then", i.e. it only have the "else" part.
> > Which sounds fine to me.
> >
> > Earlier in the document, 'when' is described as an 'if' statement
> without an 'else' clause. That makes
> > sense to me. The 'else' clause is completely optional. i.e the 'if'
> form below does not have an 'else'
> >
> > (if (> 5 4) 'true)
> >
> > In this section of the document we are describing an 'if' without a
> 'then'. That didn't make sense to me
> > because the 'then' clause is a mandatory argument. It can be 'nil' but
> it's still mandatory.
>
> AFAIU, the text attempts to explain 'when' and 'unless' in terms if
> 'if', and it doesn't try to be rigorously correct, but rather to be
> intuitively understandable by people who may not be programmers or
> have a mathematical background. So "if without then" might not make
> sense to someone who has the "if" syntax burnt into his/her muscle
> memory, but it does make sense if you consider that "if" has a "then"
> block and an "else" block, and "unless" executes the "else" block of
> the condition.
>
> So this is why I asked Richard to review this text and your comments.
>
[Message part 2 (text/html, inline)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Fri, 17 Nov 2023 03:57:02 GMT)
Full text and
rfc822 format available.
Message #17 received at 67185 <at> debbugs.gnu.org (full text, mbox):
[[[ 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. ]]]
We should use logical terms such as "converse" only in the strictly correct
logical sense. "Converse" is not correct here.
"Inverse" also has a specific mathematical meaning, which doesn't fit
here.
What should se use here? I think "opposite" is the best word.
> > > "The ‘kill-region’ function definition also has an ‘unless’ macro; it
> > > is the opposite of ‘when’.
If people are asking me to review more of the text, would someone please
send me the entire passage I whoudl review?
--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Fri, 17 Nov 2023 07:20:01 GMT)
Full text and
rfc822 format available.
Message #20 received at 67185 <at> debbugs.gnu.org (full text, mbox):
> From: Richard Stallman <rms <at> gnu.org>
> Cc: eliz <at> gnu.org, 67185 <at> debbugs.gnu.org
> Date: Thu, 16 Nov 2023 22:56:29 -0500
>
> We should use logical terms such as "converse" only in the strictly correct
> logical sense. "Converse" is not correct here.
>
> "Inverse" also has a specific mathematical meaning, which doesn't fit
> here.
>
> What should se use here? I think "opposite" is the best word.
That manual uses "converse" and "conversely" about half a dozen times:
are all of them incorrect, and actually mean "opposite" or maybe "by
contrast"?
> > > > "The ‘kill-region’ function definition also has an ‘unless’ macro; it
> > > > is the opposite of ‘when’.
>
> If people are asking me to review more of the text, would someone please
> send me the entire passage I whoudl review?
The passage was in the original message. I reproduce its Texinfo
source below:
The @code{kill-region} function definition also has an @code{unless}
macro; it is the converse of @code{when}. The @code{unless} macro is
an @code{if} without a then clause
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Fri, 17 Nov 2023 13:24:02 GMT)
Full text and
rfc822 format available.
Message #23 received at 67185 <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
My position would be that the word 'conversely' is probably ok in those
cases where it is used. However the word 'converse', especially when talking
about conditional relationships, needs to change. I only see one such case,
the one we're talking about here.
My biggest complaint wasn't about the use of the word 'converse'. Instead,
it
was the explanation of 'unless' as an 'if without a then'. I think it needs
to
explain that it is an 'if without a then but with an else that is populated
with the expressions from the then block of the unless statement. An
example
like the one in the Lisp Reference Manual would bring it home. I'll include
that change in my patch and you can decide whether it's appropriate..
Regards,
Ryan Hodges
On Thu, Nov 16, 2023 at 11:19 PM Eli Zaretskii <eliz <at> gnu.org> wrote:
> > From: Richard Stallman <rms <at> gnu.org>
> > Cc: eliz <at> gnu.org, 67185 <at> debbugs.gnu.org
> > Date: Thu, 16 Nov 2023 22:56:29 -0500
> >
> > We should use logical terms such as "converse" only in the strictly
> correct
> > logical sense. "Converse" is not correct here.
> >
> > "Inverse" also has a specific mathematical meaning, which doesn't fit
> > here.
> >
> > What should se use here? I think "opposite" is the best word.
>
> That manual uses "converse" and "conversely" about half a dozen times:
> are all of them incorrect, and actually mean "opposite" or maybe "by
> contrast"?
>
> > > > > "The ‘kill-region’ function definition also has an ‘unless’
> macro; it
> > > > > is the opposite of ‘when’.
> >
> > If people are asking me to review more of the text, would someone please
> > send me the entire passage I whoudl review?
>
> The passage was in the original message. I reproduce its Texinfo
> source below:
>
> The @code{kill-region} function definition also has an @code{unless}
> macro; it is the converse of @code{when}. The @code{unless} macro is
> an @code{if} without a then clause
>
[Message part 2 (text/html, inline)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Sun, 19 Nov 2023 03:41:02 GMT)
Full text and
rfc822 format available.
Message #26 received at 67185 <at> debbugs.gnu.org (full text, mbox):
[[[ 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. ]]]
> 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.
--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
Reply sent
to
Eli Zaretskii <eliz <at> gnu.org>:
You have taken responsibility.
(Sun, 19 Nov 2023 10:17:01 GMT)
Full text and
rfc822 format available.
Notification sent
to
Ryan Hodges <rphodges <at> gmail.com>:
bug acknowledged by developer.
(Sun, 19 Nov 2023 10:17:01 GMT)
Full text and
rfc822 format available.
Message #31 received at 67185-done <at> debbugs.gnu.org (full text, mbox):
> From: Richard Stallman <rms <at> gnu.org>
> Cc: rphodges <at> gmail.com, 67185 <at> debbugs.gnu.org
> 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.
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Sun, 19 Nov 2023 19:02:02 GMT)
Full text and
rfc822 format available.
Message #34 received at 67185-done <at> debbugs.gnu.org (full text, mbox):
[Message part 1 (text/plain, inline)]
Thank you both. After I finish learning Elisp, I hope I can make some real
contributions.
Cheers,
Ryan Hodges
On Sun, Nov 19, 2023 at 2:16 AM Eli Zaretskii <eliz <at> gnu.org> wrote:
> > From: Richard Stallman <rms <at> gnu.org>
> > Cc: rphodges <at> gmail.com, 67185 <at> debbugs.gnu.org
> > 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.
>
[Message part 2 (text/html, inline)]
Information forwarded
to
bug-gnu-emacs <at> gnu.org:
bug#67185; Package
emacs.
(Tue, 21 Nov 2023 02:43:02 GMT)
Full text and
rfc822 format available.
Message #37 received at 67185-done <at> debbugs.gnu.org (full text, mbox):
[[[ 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. ]]]
Thanks for helping to improve documentation. It is a very important task
and only a few people put much effort into it.
--
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
bug archived.
Request was from
Debbugs Internal Request <help-debbugs <at> gnu.org>
to
internal_control <at> debbugs.gnu.org.
(Tue, 19 Dec 2023 12:24:09 GMT)
Full text and
rfc822 format available.
This bug report was last modified 1 year and 170 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.