bug#8770: 24.0.50; unhelpful use of "unflag" in some Dired doc strings

bug#8770: 24.0.50; unhelpful use of "unflag" in some Dired doc strings

[Drew Adams]

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'
 

bug#8770: 24.0.50; unhelpful use of "unflag" in some Dired doc strings

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Here are the problematic doc strings, where "unflag" should be changed
> to "unmark", or to "unmark or unflag" if `D' is also affected:

I've now applied your suggested changes.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/