bug#25461: [Patch]: Missing doc strings for "," and ",@".

[Michael Heerdegen <michael_heerdegen@web.de>]

Hello Alan,

> pcase causes ` to be expanded by the macro \`--pcase-macroexpander in
> place of the macro \`.  What is that if it is not pcase redefining `?

pcase patterns are not evaluated normally.  When ` is used in patterns,
the definition of ` is not consulted.  Just like in

(let ((l '(\` 1 2)))
  (when (eq (car l) '\`)
    (apply #'+ (cdr l))))
==> 3

Is that code redefining "`"?

You mean something different with the term "definition": a complete
summarisation of the semantics of something in any context.  Something
like that doesn't exist in a programmable extensible language like Lisp.


> I disagree with you, here.  I'm describing the simple straighforward
> normal effect of ,.  I don't understand why you're making such a big
> deal out of it.

I don't want that we change the docs to the worse.


> > ... because it is undefined.
>
> It is defined.  I intend that definition to be in a doc string.

It is implicitly given a meaning by the implementation of "`".  That's
why it's documented in the documentation of "`".  For the same reason
that there is no separate documentation for :group just because it has a
meaning in defcustom, or there is no mentioning in the docstring that
the symbol `error' has a different meaning as car of a list that is an
error handler in condition-case, or that car has a different meaning in
(setf (car something) ...) or...

All these examples appear in symbolic expressions (i.e. lists) that are
not evaluated normally.  Like in the tiny example above.  If we try to
mention what a symbol potentially could mean in any sexp that is not
evaluated normally in this symbol's docstring, our documentation would
become very messy, because lists that are not evaluated normally are
very common in Lisp.  That's why we normally collect this information in
the documentation of the functions/macros that implement this meaning.
This is not a problem because it's easy to look at the context and
consult the documentation of the surrounding form.


> > So how it is used is arbitrary.
>
> If that were the case, Emacs wouldn't even build.

The introduction of pcase didn't cause Emacs not to build.  Simply
because it didn't change the definition of `.


> > We should not say that "," "does" something, because this makes no
> > sense and leads a person reading this to false assumptions.
>
> It will enable them to understand code they are reading, and to start
> writing ` constructs themselves.

But it won't really enable them to understand how it works.


> Here is the latest proposed version of the doc string for ,,
> incorporating some of the comments you've made.
>
>
>         "`,' causes the next form to be evaluated and inserted.
>     It occurs in `\\=`' constructs.
>
>     For example:
>
>     b              => (ba bb bc)            ; assume b has this value
>     \\=`(a ,b c)      => (a (ba bb bc) c)   ; insert the value of b
>
>     See also `\\=`' and `,@'.
>
>     (Note that ``' constructs (including `,'s) sometimes have different
>     semantics.  This occurs, for example, with the macro `pcase' and other
>     macros with similar names.")

I still think it's an error to describe a global semantics that as such
isn't existent.

I would rather prefer a wording (sorry if it's poor, my English is not
so super...) like

  ", before a symbolic expression X forms a read syntax that the Lisp
  reader expands like ,X -> (, X).  Such symbolic expressions have a
  special meaning in backquote forms (see ``') and in `pcase' patterns -
  see there."

I think it would be ok to append your backquote example above.


Regards,

Michael.