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

[Michael Heerdegen]

Alan Mackenzie <acm@muc.de> writes:

> > > +;; 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.
>
> Yes.  All these things are true, aren't they?

That `,' "signals" something is too vague to be true or false.  As an
explanation of things, I don't find it good, and in the generality that
this sentence is speaking, I would say it's wrong.

That "," can only appear inside "`" is simply wrong.  That there are
currently no counterexamples in our sources doesn't make a wrong
sentence right.  And I don't think I'm exaggerating here.  Elisp is a
Lisp, and Lisp is a programmable programming language.  We want users to
extend Emacs, and we want developers to extend (E)Lisp, because that is
a big strength of the language.  Formulating rules that are not true but
restrict our usage of the language is bad.

It is also not the case that `pcase' redefines "`".  And yes, I've seen
uses of "," outside of "`" in Lisp.  And it's perfectly fine to use ","
for anything anyone wants - like any other symbol.

You doesn't seem to be confused by the fact that `rx' "(re-)uses" `and',
`or' etc.  What makes "`" different?  The fact that it is a "reader
macro"?

> > 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.
>
> I'm not sure I'm following you here.  A high level description of a
> function necessarily involves a mental model.

Maybe.  But you are describing properties of your mental model instead
of properties of the language.  Your mental model led you to confusion
and wrong conclusions.  It's not optimal to describe these things.  It
will confuse others.

> ` has a specific meaning, and has had a high quality doc string for
> ever.

Because it has a `symbol-function'.

> , likewise has a specific meaning,

That's one part that led you to confusion.

> but doesn't yet have a doc string.

... because it is undefined.

> > 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.
>
> We don't do that for other functions.  A function's doc string should be
> a crisp summary of what a function _does_.  A doc string which directs
> people to a manual, or is so confusing or unspecific that the reader is
> forced to open a manual, is a failed doc string.

But that's exactly the point: "," is not a function or a macro.  So how
it is used is arbitrary.  It's traditionally used by "`", but it's not
restricted to that.  There may be even more use cases in future Elisp.
And that is good.

> , has a definite precise function (disregarding its use in pcase for
> now).  Have you any specific suggestions on how to improve my wording of
> its doc string?
>
> > +            ((get function 'reader-macro)
> > +                  "a reader macro")
>
> > We don't have reader macros in Emacs.
>
> The reader performs macro-like actions.  What is the correct alternative
> term for what the reader does with ', `, ,, #', etc.?

The manual seems to prefer the term "reader syntax".  I think we could
use this term.

You can say that the reader expands `X to (` X), and that "`" is a
defined macro.  You can say that the reader expands ,X to (\, X), and
that a frequent usage is in backquote forms.  We should not say that ","
"does" something, because this makes no sense and leads a person reading
this to false assumptions.


Regards,

Michael.