* 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-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: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 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: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-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).