GNU bug report logs - #25462
Out of date doc string for "`".

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 25462 in the body.
You can then email your comments to 25462 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: bug-gnu-emacs <at> gnu.org
Subject: Out of date doc string for "`".
Date: Mon, 16 Jan 2017 21:30:51 +0000

Hello, Emacs.

The doc string for "`" has become partial.

It fails to mention that "`" has a radically different meaning when used
in certain parts of a `pcase', and probably quite a few other similar
macros.

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #8 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Mon, 16 Jan 2017 16:52:36 -0500

On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm <at> muc.de> wrote:
> Hello, Emacs.
>
> The doc string for "`" has become partial.
>
> It fails to mention that "`" has a radically different meaning when used
> in certain parts of a `pcase', and probably quite a few other similar
> macros.

I don't think that makes sense. Similarly, we don't add a mention of
`cl-loop's use of `if' in the docstring of `if', because that's not
part of the `if' special form. It's just a use of `if' as a plain
symbol.

Message #11 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Tue, 17 Jan 2017 20:05:39 +0000

Hello, Noam.

On Mon, Jan 16, 2017 at 04:52:36PM -0500, Noam Postavsky wrote:
> On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm <at> muc.de> wrote:
> > Hello, Emacs.

> > The doc string for "`" has become partial.

> > It fails to mention that "`" has a radically different meaning when used
> > in certain parts of a `pcase', and probably quite a few other similar
> > macros.

> I don't think that makes sense. Similarly, we don't add a mention of
> `cl-loop's use of `if' in the docstring of `if', because that's not
> part of the `if' special form. It's just a use of `if' as a plain
> symbol.

I don't think `if' inside cl-loop is liable to cause much confusion.
pcase, on the other hand, does cause confusion, as it radically changes
the meaning of symbols contained within it, something that other macros
don't do - with the possible minor exception of cl-loop.

If you can think of any other such examples of context dependence
changing the semantics, I think these should be documented too.

The direction I'm coming from is to make the doc strings help users -
not to make them 100% consistent.

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #14 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: John Mastro <john.b.mastro <at> gmail.com>
To: 25462 <at> debbugs.gnu.org
Cc: Alan Mackenzie <acm <at> muc.de>,
 Noam Postavsky <npostavs <at> users.sourceforge.net>
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Tue, 17 Jan 2017 13:17:27 -0800

Noam Postavsky <npostavs <at> users.sourceforge.net> wrote:
> On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm <at> muc.de> wrote:
>> Hello, Emacs.
>>
>> The doc string for "`" has become partial.
>>
>> It fails to mention that "`" has a radically different meaning when used
>> in certain parts of a `pcase', and probably quite a few other similar
>> macros.
>
> I don't think that makes sense. Similarly, we don't add a mention of
> `cl-loop's use of `if' in the docstring of `if', because that's not
> part of the `if' special form. It's just a use of `if' as a plain
> symbol.

Since the misunderstanding is believing that "`" is more special than it
is, maybe something calling out its ordinariness could be appropriate
(and throw in a reference to pcase as an example?)

I don't think this is great, but, as an example:

    Note that `\\=`' is any ordinary Lisp symbol and thus may be treated
    as data or given different meanings in particular contexts. For
    instance, it has a special meaning inside `pcase' patterns.

Message #17 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: npostavs <at> users.sourceforge.net
To: Alan Mackenzie <acm <at> muc.de>
Cc: 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Tue, 17 Jan 2017 21:04:48 -0500

Alan Mackenzie <acm <at> muc.de> writes:

> Hello, Noam.
>
> On Mon, Jan 16, 2017 at 04:52:36PM -0500, Noam Postavsky wrote:
>> On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm <at> muc.de> wrote:
>> > Hello, Emacs.
>
>> > The doc string for "`" has become partial.
>
>> > It fails to mention that "`" has a radically different meaning when used
>> > in certain parts of a `pcase', and probably quite a few other similar
>> > macros.
>
>> I don't think that makes sense. Similarly, we don't add a mention of
>> `cl-loop's use of `if' in the docstring of `if', because that's not
>> part of the `if' special form. It's just a use of `if' as a plain
>> symbol.
>
> I don't think `if' inside cl-loop is liable to cause much confusion.
> pcase, on the other hand, does cause confusion, as it radically changes
> the meaning of symbols contained within it, something that other macros
> don't do - with the possible minor exception of cl-loop.
>
> If you can think of any other such examples of context dependence
> changing the semantics, I think these should be documented too.

`rx' gives new semantics to `and', `or', `any', etc...

`condition-case' changes the meaning of the symbol list at the front of
its handlers.

At one point, the `use-package' macro (note, this is not (yet) part of
Emacs) interpreted `,' to mean eager evaluation.  But people didn't like
it, so it now uses `lambda' for that instead.

> The direction I'm coming from is to make the doc strings help users -
> not to make them 100% consistent.

Well, I guess adding a mention of pcase in backquote's docstring would
be okay.  The way your initial report phrases it, as if the docstring is
incomplete without that, didn't make sense to me.

Message #20 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Wed, 18 Jan 2017 20:40:08 +0000

Hello again, Noam.

On Mon, Jan 16, 2017 at 04:52:36PM -0500, Noam Postavsky wrote:
> On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm <at> muc.de> wrote:
> > Hello, Emacs.

> > The doc string for "`" has become partial.

> > It fails to mention that "`" has a radically different meaning when used
> > in certain parts of a `pcase', and probably quite a few other similar
> > macros.

> I don't think that makes sense. Similarly, we don't add a mention of
> `cl-loop's use of `if' in the docstring of `if', because that's not
> part of the `if' special form. It's just a use of `if' as a plain
> symbol.

In cl-loop, you might have "if", but you're never going to have "(if
...", are you?  If this is correct, then `if' is not used in a way that
could be confused with the special form.

This doesn't apply to ` as used in pcase.

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #23 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: John Mastro <john.b.mastro <at> gmail.com>
Cc: 25462 <at> debbugs.gnu.org, Noam Postavsky <npostavs <at> users.sourceforge.net>
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Wed, 18 Jan 2017 20:55:25 +0000

Hello, John.

On Tue, Jan 17, 2017 at 01:17:27PM -0800, John Mastro wrote:
> Noam Postavsky <npostavs <at> users.sourceforge.net> wrote:
> > On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm <at> muc.de> wrote:
> >> Hello, Emacs.

> >> The doc string for "`" has become partial.

> >> It fails to mention that "`" has a radically different meaning when used
> >> in certain parts of a `pcase', and probably quite a few other similar
> >> macros.

> > I don't think that makes sense. Similarly, we don't add a mention of
> > `cl-loop's use of `if' in the docstring of `if', because that's not
> > part of the `if' special form. It's just a use of `if' as a plain
> > symbol.

> Since the misunderstanding is believing that "`" is more special than it
> is, maybe something calling out its ordinariness could be appropriate
> (and throw in a reference to pcase as an example?)

"`" is very special.  So special, indeed, that its syntax is handled by
the Lisp reader.

> I don't think this is great, but, as an example:

>     Note that `\\=`' is any ordinary Lisp symbol and thus may be treated
>     as data or given different meanings in particular contexts. For
>     instance, it has a special meaning inside `pcase' patterns.

I think that's objectively wrong.  "`" isn't an ordinary Lisp symbol,
it's a reader macro which is handled in the reader.  There aren't many
of these macros, and only a very few in normal use.

Besides, we don't want to encourage people to reuse existing symbols for
unconnected purposes.

-- 
Alan Mackenzie (Nuremberg, Germany).

Message #26 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Alan Mackenzie <acm <at> muc.de>
Cc: John Mastro <john.b.mastro <at> gmail.com>, 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Wed, 18 Jan 2017 17:14:10 -0500

On Wed, Jan 18, 2017 at 3:55 PM, Alan Mackenzie <acm <at> muc.de> wrote:
>
>>     Note that `\\=`' is any ordinary Lisp symbol and thus may be treated
>>     as data or given different meanings in particular contexts. For
>>     instance, it has a special meaning inside `pcase' patterns.
>
> I think that's objectively wrong.

It's correct.

>  "`" isn't an ordinary Lisp symbol,
> it's a reader macro which is handled in the reader.

It's both.  "`" is a reader macro which expands into a list starting
with the ordinary Lisp symbol named "`".

(equal (car (read-from-string "`a"))
       (list (intern "`") 'a)) ;=> t

Message #29 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Sat, 25 Sep 2021 09:12:37 -0700

Alan Mackenzie <acm <at> muc.de> writes:

> Hello, Emacs.
>
> The doc string for "`" has become partial.
>
> It fails to mention that "`" has a radically different meaning when used
> in certain parts of a `pcase', and probably quite a few other similar
> macros.

How about adding this at the very end of the ` docstring:

    Note that some macros, such as `pcase', change the meaning of this
    symbol.

Message #32 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Alan Mackenzie <acm <at> muc.de>, 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Sun, 26 Sep 2021 08:46:33 +0200

Stefan Kangas <stefan <at> marxist.se> writes:

> How about adding this at the very end of the ` docstring:
>
>     Note that some macros, such as `pcase', change the meaning of this
>     symbol.

I added

Note that some macros, such as `pcase', use this symbol for other
purposes.

to Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #37 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Alan Mackenzie <acm <at> muc.de>, 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Sun, 26 Sep 2021 00:17:30 -0700

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> Stefan Kangas <stefan <at> marxist.se> writes:
>
>> How about adding this at the very end of the ` docstring:
>>
>>     Note that some macros, such as `pcase', change the meaning of this
>>     symbol.
>
> I added
>
> Note that some macros, such as `pcase', use this symbol for other
> purposes.
>
> to Emacs 28.

Yes, that's even better.  Thanks.

Message #40 received at 25462 <at> debbugs.gnu.org (full text, mbox):

From: Alan Mackenzie <acm <at> muc.de>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 25462 <at> debbugs.gnu.org
Subject: Re: bug#25462: Out of date doc string for "`".
Date: Sun, 26 Sep 2021 20:31:17 +0000

Hello, Lars and Stefan.

On Sun, Sep 26, 2021 at 00:17:30 -0700, Stefan Kangas wrote:
> Lars Ingebrigtsen <larsi <at> gnus.org> writes:

> > Stefan Kangas <stefan <at> marxist.se> writes:

> >> How about adding this at the very end of the ` docstring:

> >>     Note that some macros, such as `pcase', change the meaning of this
> >>     symbol.

> > I added

> > Note that some macros, such as `pcase', use this symbol for other
> > purposes.

> > to Emacs 28.

> Yes, that's even better.  Thanks.

Thanks for the fix!

-- 
Alan Mackenzie (Nuremberg, Germany).

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.