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: Thu, 19 Jan 2017 03:23:32 +0100 [thread overview]
Message-ID: <87lgu7dbyz.fsf@web.de> (raw)
In-Reply-To: <20170118194320.GB4108@acm.fritz.box> (Alan Mackenzie's message of "Wed, 18 Jan 2017 19:43:20 +0000")
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
next prev parent reply other threads:[~2017-01-19 2:23 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 [this message]
2017-01-19 17:58 ` Alan Mackenzie
2017-01-20 0:12 ` Michael Heerdegen
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=87lgu7dbyz.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.