From: "Drew Adams" <drew.adams@oracle.com>
To: 8770@debbugs.gnu.org
Subject: bug#8770: 24.0.50; unhelpful use of "unflag" in some Dired doc strings
Date: Mon, 30 May 2011 21:20:11 -0700 [thread overview]
Message-ID: <FE607CFD7CDB42D7AAB16982C59A7833@us.oracle.com> (raw)
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'
next reply other threads:[~2011-05-31 4:20 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-05-31 4:20 Drew Adams [this message]
2011-07-06 17:11 ` bug#8770: 24.0.50; unhelpful use of "unflag" in some Dired doc strings Lars Magne Ingebrigtsen
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=FE607CFD7CDB42D7AAB16982C59A7833@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=8770@debbugs.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.
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.