From: Alan Mackenzie <acm@muc.de>
To: Michael Heerdegen <michael_heerdegen@web.de>
Cc: 25461@debbugs.gnu.org
Subject: bug#25461: [Patch]: Missing doc strings for "," and ",@".
Date: Sat, 21 Jan 2017 15:56:51 +0000 [thread overview]
Message-ID: <20170121155651.GB5394@acm> (raw)
In-Reply-To: <87y3y5cfnl.fsf@web.de>
Hello, Michael.
On Sat, Jan 21, 2017 at 03:26:06 +0100, Michael Heerdegen wrote:
> Hello Alan,
[ .... ]
> I don't want that we change the docs to the worse.
I somehow don't think you'll be happy with any modifications I make to
the proposed doc strings which leaves their basic structure unchanged.
How about starting on a different tack. Would you accept , and ,@
having doc strings, with the entirety of these being:
[for ,]:
See ``' (and also `pcase') for the details of `,'.
[for ,@]:
See ``' for the details of `,@'.
?
[ .... ]
> 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.
, and ,@ are different: it is not obvious to the unexperienced what
"sexp" they belong to in something like
`(if ,cond (progn ,@body))
. How is a beginner supposed to connect up the ,@ in that example with
the ` which doesn't directly enclose or otherwise connect with it?
[ .... ]
(I'll address your points that I've snipped if they become relevant
again.)
> Regards,
> Michael.
--
Alan Mackenzie (Nuremberg, Germany).
next prev parent reply other threads:[~2017-01-21 15:56 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
2017-01-20 16:58 ` Alan Mackenzie
2017-01-21 2:26 ` Michael Heerdegen
2017-01-21 15:56 ` Alan Mackenzie [this message]
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=20170121155651.GB5394@acm \
--to=acm@muc.de \
--cc=25461@debbugs.gnu.org \
--cc=michael_heerdegen@web.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.