From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#8770: 24.0.50; unhelpful use of "unflag" in some Dired doc strings Date: Mon, 30 May 2011 21:20:11 -0700 Message-ID: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1306815672 540 80.91.229.12 (31 May 2011 04:21:12 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 31 May 2011 04:21:12 +0000 (UTC) To: 8770@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue May 31 06:21:08 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QRGS4-0004zo-7s for geb-bug-gnu-emacs@m.gmane.org; Tue, 31 May 2011 06:21:08 +0200 Original-Received: from localhost ([::1]:57816 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRGS3-0006sR-Gd for geb-bug-gnu-emacs@m.gmane.org; Tue, 31 May 2011 00:21:07 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:57831) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRGS0-0006s9-1Y for bug-gnu-emacs@gnu.org; Tue, 31 May 2011 00:21:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QRGRz-000294-1R for bug-gnu-emacs@gnu.org; Tue, 31 May 2011 00:21:04 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:57697) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRGRy-000290-W6 for bug-gnu-emacs@gnu.org; Tue, 31 May 2011 00:21:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QRGRy-0002dX-Jm; Tue, 31 May 2011 00:21:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 31 May 2011 04:21:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 8770 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: Original-Received: via spool by submit@debbugs.gnu.org id=B.130681563210093 (code B ref -1); Tue, 31 May 2011 04:21:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 31 May 2011 04:20:32 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QRGRT-0002ck-KA for submit@debbugs.gnu.org; Tue, 31 May 2011 00:20:31 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QRGRR-0002cY-Rf for submit@debbugs.gnu.org; Tue, 31 May 2011 00:20:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QRGRL-00025v-Ib for submit@debbugs.gnu.org; Tue, 31 May 2011 00:20:24 -0400 Original-Received: from lists.gnu.org ([140.186.70.17]:36548) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRGRL-00025r-Ft for submit@debbugs.gnu.org; Tue, 31 May 2011 00:20:23 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:57722) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRGRK-0006r3-3H for bug-gnu-emacs@gnu.org; Tue, 31 May 2011 00:20:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QRGRJ-00025U-4P for bug-gnu-emacs@gnu.org; Tue, 31 May 2011 00:20:22 -0400 Original-Received: from rcsinet10.oracle.com ([148.87.113.121]:34512) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRGRI-00025Q-Ux for bug-gnu-emacs@gnu.org; Tue, 31 May 2011 00:20:21 -0400 Original-Received: from rtcsinet21.oracle.com (rtcsinet21.oracle.com [66.248.204.29]) by rcsinet10.oracle.com (Switch-3.4.2/Switch-3.4.2) with ESMTP id p4V4KIdT022083 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 31 May 2011 04:20:20 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by rtcsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p4V4KGV5000531 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 31 May 2011 04:20:17 GMT Original-Received: from abhmt010.oracle.com (abhmt010.oracle.com [141.146.116.19]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p4V4KBgn031172 for ; Mon, 30 May 2011 23:20:11 -0500 Original-Received: from dradamslap1 (/10.159.49.144) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 30 May 2011 21:20:11 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: AcwfSghWl/fG6b7lTm+3gKocanAPnQ== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6090 X-Source-IP: rtcsinet21.oracle.com [66.248.204.29] X-CT-RefId: str=0001.0A090201.4DE46C84.0087:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 31 May 2011 00:21:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:46835 Archived-At: 1. For Dired, Emacs generally has the convention of speaking of "flagging for deletion" when it means adding the mark `D'. See the doc in general, and see for example things like `dired-del-marker', face `dired-flagged', the feedback message from `dired-mark-if', and the doc strings of `dired', `dired-flag-file-deletion', and `dired-mode' (except for a typo - see below). For marks other than `D' Emacs speaks of "marking", but not for `D'. And it generally does not speak of flagging except for marking with `D'. It is true that in some contexts that deal with multiple kinds of marks together, Emacs talks of "marks", including `D' flags with this term. But the verb used for adding `D' marks is always "flag", I believe. Consider, for instance, the :help string for `dired-toggle-marks': "Mark unmarked files, unmark marked ones". Marked files here do not include the flagged files (those marked with `D'). This is the advantage of having introduced a special term ("flag") for just the deletion mark. Apart from the terminology convention introduced by Emacs, the words "mark" and "flag" are general; neither is specific to any kind of mark. IOW, it is only Emacs that associates "flag" with deletion. But this distinction is helpful for communicating, because many Emacs operations act only wrt `D' marks or only wrt non-`D' marks. This bug report is about a few doc strings that use "unflag" to mean unmark in general, that is, removal of marks of all kinds. In these cases, it would be clearer to use "unmark". Search for "[Uu]nflag" in dired.el. The first occurrence, which is for the :help of the `dired-unmark' key binding, is a good guide for what _should_ be done: "Unmark or unflag current line's file". It explicitly distinguishes "unflag" as the removal of `D' marks, even though it did not absolutely need to do so since "unmark" could signify all kinds of marks. What it does is the right thing, as it adds clarity. The same should be done elsewhere as well. Another positive example is the doc string of `dired-revert', which refers to "marks/flags". Even some comments in dired.el make the distinction - e.g. ";; Commands to mark or flag certain categories of files" and ";; Commands to mark or flag file(s) at or near current line." Here are the problematic doc strings, where "unflag" should be changed to "unmark", or to "unmark or unflag" if `D' is also affected: a. `dired-mode': "Type \\[dired-unmark-backward] to back up one line and unflag." b. `dired-unmark-backward' "In Dired, move up lines and remove deletion flag there. Optional prefix ARG says how many lines to unflag; default is one line." This operation affects all marks, including but not only `D'. The doc should say that - it should use "unmark or unflag", not "unflag", and the first line is just incorrect - it does not just remove deletion flags. c. These commands all have this or similar in their doc strings: "With prefix argument, unflag all those files." They should all say "unmark or unflag", because all kinds of marks are removed. `dired-mark-symlinks', `dired-mark-directories', `dired-mark-executables', `dired-mark-sexp' (in dired-x.el), d. `dired-flag-auto-save-files' and `dired-flag-backup-files' correctly say that they flag the files for deletion. But they incorrectly say that with a prefix arg they unflag them. In fact, with a prefix arg they unmark or unflag them. IOW, if you mark a file #foo# with `*' then `C-u #' will unmark it, and likewise for a file foo~. In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600) of 2011-05-23 on 3249CTO Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (4.5) --no-opt --cflags -Ic:/build/include'