* bug#25462: Out of date doc string for "`".
@ 2017-01-16 21:30 Alan Mackenzie
2017-01-16 21:52 ` Noam Postavsky
2021-09-25 16:12 ` Stefan Kangas
0 siblings, 2 replies; 12+ messages in thread
From: Alan Mackenzie @ 2017-01-16 21:30 UTC (permalink / raw)
To: 25462
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).
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-16 21:30 bug#25462: Out of date doc string for "`" Alan Mackenzie
@ 2017-01-16 21:52 ` Noam Postavsky
2017-01-17 20:05 ` Alan Mackenzie
` (2 more replies)
2021-09-25 16:12 ` Stefan Kangas
1 sibling, 3 replies; 12+ messages in thread
From: Noam Postavsky @ 2017-01-16 21:52 UTC (permalink / raw)
To: Alan Mackenzie; +Cc: 25462
On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm@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.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-16 21:52 ` Noam Postavsky
@ 2017-01-17 20:05 ` Alan Mackenzie
2017-01-18 2:04 ` npostavs
2017-01-17 21:17 ` John Mastro
2017-01-18 20:40 ` Alan Mackenzie
2 siblings, 1 reply; 12+ messages in thread
From: Alan Mackenzie @ 2017-01-17 20:05 UTC (permalink / raw)
To: Noam Postavsky; +Cc: 25462
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@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).
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-16 21:52 ` Noam Postavsky
2017-01-17 20:05 ` Alan Mackenzie
@ 2017-01-17 21:17 ` John Mastro
2017-01-18 20:55 ` Alan Mackenzie
2017-01-18 20:40 ` Alan Mackenzie
2 siblings, 1 reply; 12+ messages in thread
From: John Mastro @ 2017-01-17 21:17 UTC (permalink / raw)
To: 25462; +Cc: Alan Mackenzie, Noam Postavsky
Noam Postavsky <npostavs@users.sourceforge.net> wrote:
> On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm@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.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-17 20:05 ` Alan Mackenzie
@ 2017-01-18 2:04 ` npostavs
0 siblings, 0 replies; 12+ messages in thread
From: npostavs @ 2017-01-18 2:04 UTC (permalink / raw)
To: Alan Mackenzie; +Cc: 25462
Alan Mackenzie <acm@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@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.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-16 21:52 ` Noam Postavsky
2017-01-17 20:05 ` Alan Mackenzie
2017-01-17 21:17 ` John Mastro
@ 2017-01-18 20:40 ` Alan Mackenzie
2 siblings, 0 replies; 12+ messages in thread
From: Alan Mackenzie @ 2017-01-18 20:40 UTC (permalink / raw)
To: Noam Postavsky; +Cc: 25462
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@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).
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-17 21:17 ` John Mastro
@ 2017-01-18 20:55 ` Alan Mackenzie
2017-01-18 22:14 ` Noam Postavsky
0 siblings, 1 reply; 12+ messages in thread
From: Alan Mackenzie @ 2017-01-18 20:55 UTC (permalink / raw)
To: John Mastro; +Cc: 25462, Noam Postavsky
Hello, John.
On Tue, Jan 17, 2017 at 01:17:27PM -0800, John Mastro wrote:
> Noam Postavsky <npostavs@users.sourceforge.net> wrote:
> > On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm@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).
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-18 20:55 ` Alan Mackenzie
@ 2017-01-18 22:14 ` Noam Postavsky
0 siblings, 0 replies; 12+ messages in thread
From: Noam Postavsky @ 2017-01-18 22:14 UTC (permalink / raw)
To: Alan Mackenzie; +Cc: John Mastro, 25462
On Wed, Jan 18, 2017 at 3:55 PM, Alan Mackenzie <acm@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
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2017-01-16 21:30 bug#25462: Out of date doc string for "`" Alan Mackenzie
2017-01-16 21:52 ` Noam Postavsky
@ 2021-09-25 16:12 ` Stefan Kangas
2021-09-26 6:46 ` Lars Ingebrigtsen
1 sibling, 1 reply; 12+ messages in thread
From: Stefan Kangas @ 2021-09-25 16:12 UTC (permalink / raw)
To: Alan Mackenzie; +Cc: 25462
Alan Mackenzie <acm@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.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2021-09-25 16:12 ` Stefan Kangas
@ 2021-09-26 6:46 ` Lars Ingebrigtsen
2021-09-26 7:17 ` Stefan Kangas
0 siblings, 1 reply; 12+ messages in thread
From: Lars Ingebrigtsen @ 2021-09-26 6:46 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Alan Mackenzie, 25462
Stefan Kangas <stefan@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
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2021-09-26 6:46 ` Lars Ingebrigtsen
@ 2021-09-26 7:17 ` Stefan Kangas
2021-09-26 20:31 ` Alan Mackenzie
0 siblings, 1 reply; 12+ messages in thread
From: Stefan Kangas @ 2021-09-26 7:17 UTC (permalink / raw)
To: Lars Ingebrigtsen; +Cc: Alan Mackenzie, 25462
Lars Ingebrigtsen <larsi@gnus.org> writes:
> Stefan Kangas <stefan@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.
^ permalink raw reply [flat|nested] 12+ messages in thread
* bug#25462: Out of date doc string for "`".
2021-09-26 7:17 ` Stefan Kangas
@ 2021-09-26 20:31 ` Alan Mackenzie
0 siblings, 0 replies; 12+ messages in thread
From: Alan Mackenzie @ 2021-09-26 20:31 UTC (permalink / raw)
To: Stefan Kangas; +Cc: Lars Ingebrigtsen, 25462
Hello, Lars and Stefan.
On Sun, Sep 26, 2021 at 00:17:30 -0700, Stefan Kangas wrote:
> Lars Ingebrigtsen <larsi@gnus.org> writes:
> > Stefan Kangas <stefan@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).
^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2021-09-26 20:31 UTC | newest]
Thread overview: 12+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-01-16 21:30 bug#25462: Out of date doc string for "`" Alan Mackenzie
2017-01-16 21:52 ` Noam Postavsky
2017-01-17 20:05 ` Alan Mackenzie
2017-01-18 2:04 ` npostavs
2017-01-17 21:17 ` John Mastro
2017-01-18 20:55 ` Alan Mackenzie
2017-01-18 22:14 ` Noam Postavsky
2017-01-18 20:40 ` Alan Mackenzie
2021-09-25 16:12 ` Stefan Kangas
2021-09-26 6:46 ` Lars Ingebrigtsen
2021-09-26 7:17 ` Stefan Kangas
2021-09-26 20:31 ` Alan Mackenzie
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).