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

[Michael Heerdegen <michael_heerdegen@web.de>]

Hi Alan,

> diff --git a/lisp/emacs-lisp/backquote.el b/lisp/emacs-lisp/backquote.el
> index 94c561c..86ca010 100644
> --- a/lisp/emacs-lisp/backquote.el
> +++ b/lisp/emacs-lisp/backquote.el
> @@ -247,4 +247,33 @@ backquote-listify
>  	tail))
>       (t (cons 'list heads)))))
>  
> +\f
> +;; Give `,' and `,@' documentation strings which can be examined by C-h f.
> +(put '\, 'function-documentation
> +     "`,' signals that the next form should be evaluated and inserted.
> +It can occur only 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 `,@'.

I don't think this makes it easier for people to understand things.
This suggests that "," has some kind of meaning per se, that it is a
macro-like thing, etc, and that pcase somehow redefines it.

Of course there is a logic behind pcase's usage of ` and ,.  The
usage of these suggests a mental model for their "meaning".  But we
should not describe our mental models in docstrings.  That's only useful
for people sharing the same model.

The bindings of variables depend on context.  The semantics of functions
are fluent (advice, local functions).  And also the "meaning" of the
sexps created by ` and , depend on the context - in Lisp, the "meaning"
of all sexps depends on context.  (foo bar) can be a function call or a
part of a let variable binding or a list or a pcase pattern.  It's not
different for sexps involving `.

So I think we maximally should describe what the reader does with `
etc., so that people know what to search for in the manual or remember
what they already had learned.


+		 ((get function 'reader-macro)
+                  "a reader macro")

We don't have reader macros in Emacs.  If we had them, we could
implement ', ` etc. as reader macros.  But using this term in H-f is
confusing, because it is not used in the manual.



Regards,

Michael