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

Previous Next

Full log

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.

Previous Next

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