From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs,gmane.emacs.pretest.bugs Subject: bug#907: 23.0.60; doc string for dired-do-create-files Date: Sat, 6 Sep 2008 15:55:26 -0700 Message-ID: <000601c91073$a7951aa0$0200a8c0@us.oracle.com> References: <000501c91070$5bc6b320$0200a8c0@us.oracle.com> Reply-To: Drew Adams , 907@emacsbugs.donarmstrong.com NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1220742478 25667 80.91.229.12 (6 Sep 2008 23:07:58 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 6 Sep 2008 23:07:58 +0000 (UTC) To: <907@emacsbugs.donarmstrong.com>, Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Sep 07 01:08:52 2008 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1Kc6tb-0004SO-Dt for geb-bug-gnu-emacs@m.gmane.org; Sun, 07 Sep 2008 01:08:48 +0200 Original-Received: from localhost ([127.0.0.1]:53462 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Kc6sa-0001tL-KR for geb-bug-gnu-emacs@m.gmane.org; Sat, 06 Sep 2008 19:07:44 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Kc6sW-0001rd-33 for bug-gnu-emacs@gnu.org; Sat, 06 Sep 2008 19:07:40 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Kc6sU-0001qE-PV for bug-gnu-emacs@gnu.org; Sat, 06 Sep 2008 19:07:39 -0400 Original-Received: from [199.232.76.173] (port=59244 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Kc6sU-0001px-7n for bug-gnu-emacs@gnu.org; Sat, 06 Sep 2008 19:07:38 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:60253) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Kc6sT-0005IE-3i for bug-gnu-emacs@gnu.org; Sat, 06 Sep 2008 19:07:37 -0400 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id m86N7VDd029931; Sat, 6 Sep 2008 16:07:32 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.13.8/8.13.8/Submit) id m86N56Ab028683; Sat, 6 Sep 2008 16:05:06 -0700 X-Loop: don@donarmstrong.com Resent-From: "Drew Adams" Resent-To: bug-submit-list@donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Sat, 06 Sep 2008 23:05:06 +0000 Resent-Message-ID: Resent-Sender: don@donarmstrong.com X-Emacs-PR-Message: report 907 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by submit@emacsbugs.donarmstrong.com id=B.122074180125764 (code B ref -1); Sat, 06 Sep 2008 23:05:06 +0000 Original-Received: (at submit) by emacsbugs.donarmstrong.com; 6 Sep 2008 22:56:41 +0000 Original-Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id m86Mub9q025758 for ; Sat, 6 Sep 2008 15:56:38 -0700 Original-Received: from mail.gnu.org ([199.232.76.166]:50702 helo=mx10.gnu.org) by fencepost.gnu.org with esmtp (Exim 4.67) (envelope-from ) id 1Kc6gA-00082E-PQ for emacs-pretest-bug@gnu.org; Sat, 06 Sep 2008 18:54:54 -0400 Original-Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1Kc6hl-0004Jm-Jh for emacs-pretest-bug@gnu.org; Sat, 06 Sep 2008 18:56:37 -0400 Original-Received: from rgminet01.oracle.com ([148.87.113.118]:32713) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Kc6hl-0004DZ-85 for emacs-pretest-bug@gnu.org; Sat, 06 Sep 2008 18:56:33 -0400 Original-Received: from rgmgw2.us.oracle.com (rgmgw2.us.oracle.com [138.1.186.111]) by rgminet01.oracle.com (Switch-3.2.4/Switch-3.1.6) with ESMTP id m86MtT9a032750; Sat, 6 Sep 2008 16:55:29 -0600 Original-Received: from acsmt702.oracle.com (acsmt702.oracle.com [141.146.40.80]) by rgmgw2.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with ESMTP id m86MtR27008145; Sat, 6 Sep 2008 16:55:27 -0600 Original-Received: from dradamslap1 (/24.23.165.218) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 06 Sep 2008 15:55:27 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <000501c91070$5bc6b320$0200a8c0@us.oracle.com> Thread-Index: AckQcFtl1AugDqtITgGm63JRzsijQAAAw2yA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.4-2.6 X-CrossAssassin-Score: 2 X-detected-kernel: by monty-python.gnu.org: Linux 2.6 (newer, 3) Resent-Date: Sat, 06 Sep 2008 19:07:39 -0400 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:20266 gmane.emacs.pretest.bugs:23001 Archived-At: I said: > This renders the doc string incomprehensible. About 2/3 of the doc > string concerns `into-dir', and it includes a seemingly ridiculously > complex explanation of arg HOW-TO, complete with > if-then-else-if-then-else-if-then-else-if-then-else (no > exaggeration!). I was a little mistaken. It's both a bit worse and a bit better than I thought. The last if-then-else-if-then-else supposedly explains HOW-TO; the first if-then-else-if-then-else supposedly explains `into-dir' (which is an internal, local variable). This is all backwards and not clear at all. What's needed is a single, straightforward explanation of HOW-TO, with no reference to `into-dir'. Looking at previous Emacs versions, I discovered that this doc string derives from a comment that was in the Emacs 20 code. The comment, which referred to local variable `into-dir', was simply copied to a (then missing) doc string. The rest still applies: > Please rewrite the doc string so that it is self-contained and > readable. It should not simply mirror the code but should make clear > to users what each argument is.