From: Michael Heerdegen <michael_heerdegen@web.de>
To: Alan Mackenzie <acm@muc.de>
Cc: 25461@debbugs.gnu.org
Subject: bug#25461: [Patch]: Missing doc strings for "," and ",@".
Date: Fri, 20 Jan 2017 01:12:18 +0100 [thread overview]
Message-ID: <877f5qbndp.fsf@web.de> (raw)
In-Reply-To: <20170119175801.GB3397@acm.fritz.box> (Alan Mackenzie's message of "Thu, 19 Jan 2017 17:58:01 +0000")
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.
next prev parent reply other threads:[~2017-01-20 0:12 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-01-16 21:22 bug#25461: Missing doc strings for "," and ",@" Alan Mackenzie
2017-01-17 19:34 ` Glenn Morris
2017-01-17 19:56 ` Alan Mackenzie
2017-01-17 20:36 ` Andreas Schwab
2017-01-17 20:41 ` Alan Mackenzie
2017-01-17 20:53 ` Andreas Schwab
2017-01-18 1:44 ` Michael Heerdegen
2017-01-18 19:28 ` Alan Mackenzie
[not found] ` <handler.25461.B.148460180922707.ack@debbugs.gnu.org>
2017-01-18 19:43 ` bug#25461: [Patch]: " Alan Mackenzie
2017-01-19 0:16 ` npostavs
2017-01-19 17:37 ` Alan Mackenzie
2017-01-19 18:10 ` Noam Postavsky
2017-01-19 18:36 ` Alan Mackenzie
2017-01-20 0:24 ` Michael Heerdegen
2017-01-19 2:23 ` Michael Heerdegen
2017-01-19 17:58 ` Alan Mackenzie
2017-01-20 0:12 ` Michael Heerdegen [this message]
2017-01-20 16:58 ` Alan Mackenzie
2017-01-21 2:26 ` Michael Heerdegen
2017-01-21 15:56 ` Alan Mackenzie
2017-01-21 20:46 ` bug#25461: [Patch #2]: " Alan Mackenzie
2017-01-24 1:58 ` Michael Heerdegen
2017-01-24 19:43 ` Alan Mackenzie
2017-01-24 4:01 ` npostavs
2017-01-24 19:39 ` Alan Mackenzie
2017-01-24 20:00 ` Noam Postavsky
2017-01-23 19:09 ` bug#25461: [Patch]: " Alan Mackenzie
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=877f5qbndp.fsf@web.de \
--to=michael_heerdegen@web.de \
--cc=25461@debbugs.gnu.org \
--cc=acm@muc.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.