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

[npostavs@users.sourceforge.net]

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.