From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Emanuel Berg Newsgroups: gmane.emacs.help Subject: Re: clear-kill-ring function Date: Thu, 29 Oct 2015 03:34:38 +0100 Message-ID: <87d1vyv1vl.fsf@debian.uxu> References: <87lhaof6tm.fsf@skimble.plus.com> <87twpcoyjy.fsf@web.de> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1446085550 24482 80.91.229.3 (29 Oct 2015 02:25:50 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 29 Oct 2015 02:25:50 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Thu Oct 29 03:25:41 2015 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1ZrcuK-0003SY-Bw for geh-help-gnu-emacs@m.gmane.org; Thu, 29 Oct 2015 03:25:40 +0100 Original-Received: from localhost ([::1]:41650 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZrcuJ-0004vJ-Kj for geh-help-gnu-emacs@m.gmane.org; Wed, 28 Oct 2015 22:25:39 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34250) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zrcu8-0004vD-3Y for help-gnu-emacs@gnu.org; Wed, 28 Oct 2015 22:25:29 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Zrcu5-0002dJ-0F for help-gnu-emacs@gnu.org; Wed, 28 Oct 2015 22:25:28 -0400 Original-Received: from plane.gmane.org ([80.91.229.3]:39376) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Zrcu4-0002dB-PX for help-gnu-emacs@gnu.org; Wed, 28 Oct 2015 22:25:24 -0400 Original-Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1Zrcu2-0003CL-Am for help-gnu-emacs@gnu.org; Thu, 29 Oct 2015 03:25:22 +0100 Original-Received: from nl106-137-244.student.uu.se ([130.243.137.244]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 29 Oct 2015 03:25:22 +0100 Original-Received: from embe8573 by nl106-137-244.student.uu.se with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Thu, 29 Oct 2015 03:25:22 +0100 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: help-gnu-emacs@gnu.org Original-Lines: 60 Original-X-Complaints-To: usenet@ger.gmane.org X-Gmane-NNTP-Posting-Host: nl106-137-244.student.uu.se Mail-Copies-To: never User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4 (gnu/linux) Cancel-Lock: sha1:hz11AfcuePPJX5HPemlLoaeewHs= X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 80.91.229.3 X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:107868 Archived-At: Joost Kremers 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