From: Emanuel Berg <embe8573@student.uu.se>
To: help-gnu-emacs@gnu.org
Subject: Re: clear-kill-ring function
Date: Thu, 29 Oct 2015 03:34:38 +0100 [thread overview]
Message-ID: <87d1vyv1vl.fsf@debian.uxu> (raw)
In-Reply-To: d9bmqhFj9rhU1@mid.individual.net
Joost Kremers <joost.m.kremers@gmail.com> writes:
> Note that the doc string should go before the
> (interactive) call ...
>
> "Clear the kill ring variable"
Docstrings should be either all user-oriented or all
technology ditto. Or both, in different paragraphs.
In general I'd say user-oriented is much better,
especially in the context of an Emacs help screen and
an interactive function, like what we have here.
However, despite being interactive, this function is
all about technology which might motivate some
tech material.
So either
"Discard all killed text."
or
"Set `kill-ring' and `kill-ring-yank-pointer'
to nil."
Or both:
"Discard all killed text.\n\nI.e., set `kill-ring' and `kill-ring-yank-pointer' to nil."
As for "Clear the kill ring variable":
1. It only explains what happens in terms of
technology, not why anyone would do that or
what is gained from a user perspective by doing
it. (Here, there purpose is unclear - why would
anyone do this? - perhaps the OP can explain
the gain of having an interactive function
do this.)
2. There are many "kill ring" variables:
kill-ring
kill-ring-max
kill-ring-yank-pointer
Which one exactly? And if there is a mention of
a variable, why not give the exact name and put
it within `whatever' to make it hyperlinked?
3. `kill-ring-max' is an integer, while
`kill-ring' and `kill-ring-yank-pointer' are or
leads to complicated data structures.
What exactly does "clear" mean? 0, nil, or an
empty data structure?
--
underground experts united
http://user.it.uu.se/~embe8573
next prev parent reply other threads:[~2015-10-29 2:34 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <mailman.1159.1445970298.7904.help-gnu-emacs@gnu.org>
2015-10-27 18:49 ` clear-kill-ring function Barry Margolin
2015-10-27 19:29 ` Sharon Kimble
2015-10-27 20:18 ` Michael Heerdegen
2015-10-28 6:06 ` Sharon Kimble
[not found] ` <mailman.1186.1446012388.7904.help-gnu-emacs@gnu.org>
2015-10-28 10:37 ` Joost Kremers
2015-10-28 12:46 ` Michael Heerdegen
2015-10-29 2:34 ` Emanuel Berg [this message]
2015-10-28 2:14 ` Emanuel Berg
2015-10-27 18:24 Sharon Kimble
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
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87d1vyv1vl.fsf@debian.uxu \
--to=embe8573@student.uu.se \
--cc=help-gnu-emacs@gnu.org \
/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.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).