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

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

[Ryan Hodges]

[-- Attachment #1: Type: text/plain, Size: 1841 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 4245 bytes --]

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

[Eli Zaretskii]

> From: Ryan Hodges <rphodges@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.

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

[Eli Zaretskii]

[Please use Reply All to reply, so that everyone is CC'ed.]

> From: Ryan Hodges <rphodges@gmail.com>
> Date: Wed, 15 Nov 2023 09:58:11 -0800
> 
> On Wed, Nov 15, 2023 at 4:18 AM Eli Zaretskii <eliz@gnu.org> wrote:
> 
>  > From: Ryan Hodges <rphodges@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.

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

[Ryan Hodges]

[-- Attachment #1: Type: text/plain, Size: 2957 bytes --]

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@gnu.org> wrote:

> [Please use Reply All to reply, so that everyone is CC'ed.]
>
> > From: Ryan Hodges <rphodges@gmail.com>
> > Date: Wed, 15 Nov 2023 09:58:11 -0800
> >
> > On Wed, Nov 15, 2023 at 4:18 AM Eli Zaretskii <eliz@gnu.org> wrote:
> >
> >  > From: Ryan Hodges <rphodges@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.
>

[-- Attachment #2: Type: text/html, Size: 4265 bytes --]

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

[Richard Stallman]

[[[ 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)

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, 67185@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

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

[Ryan Hodges]

[-- Attachment #1: Type: text/plain, Size: 1991 bytes --]

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@gnu.org> wrote:

> > From: Richard Stallman <rms@gnu.org>
> > Cc: eliz@gnu.org, 67185@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
>

[-- Attachment #2: Type: text/html, Size: 2786 bytes --]

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

[Richard Stallman]

[[[ 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)

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: rphodges@gmail.com, 67185@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.

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

[Ryan Hodges]

[-- Attachment #1: Type: text/plain, Size: 1575 bytes --]

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@gnu.org> wrote:

> > From: Richard Stallman <rms@gnu.org>
> > Cc: rphodges@gmail.com, 67185@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.
>

[-- Attachment #2: Type: text/html, Size: 2344 bytes --]

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

[Richard Stallman]

[[[ 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)