Subject: Re: bug#25462: Out of date doc string for "`".

From: Alan Mackenzie <[email-masked]>
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 <[email-masked]> 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).