bug#35572: suggested improvement to ibuffer documentation

bug#35572: suggested improvement to ibuffer documentation

[Ed Mangimelli]

Lines 2549 and 2550 of lisp/ibuffer.el read:

   `\\[ibuffer-unmark-backward]' - Unmark the buffer at point, and move 
to the
           previous line.

After using this function (bound to DEL), it seems like it should read:

   `\\[ibuffer-unmark-backward]' -  Move to the previous line and unmark the
           buffer at point.

bug#35572: suggested improvement to ibuffer documentation

[Basil L. Contovounesios]

[-- Attachment #1: Type: text/plain, Size: 992 bytes --]

tags 35572 patch
quit

Ed Mangimelli <ed.mangimelli@gmail.com> writes:

> Lines 2549 and 2550 of lisp/ibuffer.el read:
>
>   `\\[ibuffer-unmark-backward]' - Unmark the buffer at point, and move to the
>           previous line.
>
> After using this function (bound to DEL), it seems like it should read:
>
>   `\\[ibuffer-unmark-backward]' -  Move to the previous line and unmark the
>           buffer at point.

I agree that the current synopsis is incorrect, but I think it shouldn't
mention line movement at all.

Ibuffer mark commands do not always change line (e.g. when point is on a
filter group name), and the docstring of ibuffer-mode does not describe
any other marking commands as moving line, so it would be inaccurate and
inconsistent to do so for ibuffer-unmark-backward.  The synopsis need
only refer to the command's key binding and general purpose; the rest
can be left to its docstring.

So how about the following instead?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-ibuffer-unmark-backward-synopsis.patch --]
[-- Type: text/x-diff, Size: 6130 bytes --]

From 088726781c04c8f2401b580c954e184de9ce6145 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sun, 5 May 2019 16:04:26 +0100
Subject: [PATCH] Fix ibuffer-unmark-backward synopsis

* lisp/ibuffer.el (ibuffer-mark-region-or-n-with-char): Fix
indentation.
(ibuffer-mark-interactive): Remove optional third argument of
internal subroutine considered deprecated since Emacs 24.4.
(ibuffer-mark-for-delete-backwards): Don't use it.
(ibuffer-mode): Minor copy-edits.  Fix synopsis of
ibuffer-unmark-backward. (bug#35572)
---
 lisp/ibuffer.el | 32 ++++++++++++++------------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/lisp/ibuffer.el b/lisp/ibuffer.el
index 2d3c140536..efa9226e65 100644
--- a/lisp/ibuffer.el
+++ b/lisp/ibuffer.el
@@ -1477,14 +1477,11 @@ ibuffer-mark-region-or-n-with-char
         (goto-char start)
         (ibuffer-mark-interactive line-count mark-char)
         (goto-char cur))
-      (ibuffer-mark-interactive arg mark-char)))
+    (ibuffer-mark-interactive arg mark-char)))
 
-(defun ibuffer-mark-interactive (arg mark &optional movement)
+(defun ibuffer-mark-interactive (arg mark)
   (ibuffer-assert-ibuffer-mode)
   (or arg (setq arg 1))
-  ;; deprecated movement argument
-  (when (and movement (< movement 0))
-    (setq arg (- arg)))
   (ibuffer-forward-line 0)
   (ibuffer-aif (get-text-property (point) 'ibuffer-filter-group-name)
       (progn
@@ -1525,7 +1522,7 @@ ibuffer-mark-for-delete-backwards
   "Mark for deletion the ARG previous buffers.
 If point is on a group name, this function operates on that group."
   (interactive "p")
-  (ibuffer-mark-interactive arg ibuffer-deletion-char -1))
+  (ibuffer-mark-interactive (- arg) ibuffer-deletion-char))
 
 (defun ibuffer-current-buffer (&optional must-be-live)
   (let ((buf (car (get-text-property (line-beginning-position)
@@ -2507,8 +2504,8 @@ ibuffer-mode
 
 Operations on marked buffers:
 \\<ibuffer-mode-map>
-  `\\[ibuffer-do-save]' - Save the marked buffers
-  `\\[ibuffer-do-view]' - View the marked buffers in this frame.
+  `\\[ibuffer-do-save]' - Save the marked buffers.
+  `\\[ibuffer-do-view]' - View the marked buffers in the selected frame.
   `\\[ibuffer-do-view-other-frame]' - View the marked buffers in another frame.
   `\\[ibuffer-do-revert]' - Revert the marked buffers.
   `\\[ibuffer-do-toggle-read-only]' - Toggle read-only state of marked buffers.
@@ -2531,7 +2528,7 @@ ibuffer-mode
           buffer's file as an argument.
   `\\[ibuffer-do-eval]' - Evaluate a form in each of the marked buffers.  This
           is a very flexible command.  For example, if you want to make all
-          of the marked buffers read only, try using (read-only-mode 1) as
+          of the marked buffers read-only, try using (read-only-mode 1) as
           the input form.
   `\\[ibuffer-do-view-and-eval]' - As above, but view each buffer while the form
           is evaluated.
@@ -2546,21 +2543,20 @@ ibuffer-mode
           all unmarked buffers.
   `\\[ibuffer-change-marks]' - Change the mark used on marked buffers.
   `\\[ibuffer-unmark-forward]' - Unmark the buffer at point.
-  `\\[ibuffer-unmark-backward]' - Unmark the buffer at point, and move to the
-          previous line.
+  `\\[ibuffer-unmark-backward]' - Unmark the previous buffer.
   `\\[ibuffer-unmark-all]' - Unmark buffers marked with MARK.
   `\\[ibuffer-unmark-all-marks]' - Unmark all marked buffers.
   `\\[ibuffer-mark-by-mode]' - Mark buffers by major mode.
   `\\[ibuffer-mark-unsaved-buffers]' - Mark all \"unsaved\" buffers.
           This means that the buffer is modified, and has an associated file.
   `\\[ibuffer-mark-modified-buffers]' - Mark all modified buffers,
-          regardless of whether or not they have an associated file.
+          regardless of whether they have an associated file.
   `\\[ibuffer-mark-special-buffers]' - Mark all buffers whose name begins and
           ends with `*'.
   `\\[ibuffer-mark-dissociated-buffers]' - Mark all buffers which have
           an associated file, but that file doesn't currently exist.
   `\\[ibuffer-mark-read-only-buffers]' - Mark all read-only buffers.
-  `\\[ibuffer-mark-dired-buffers]' - Mark buffers in `dired' mode.
+  `\\[ibuffer-mark-dired-buffers]' - Mark buffers in `dired-mode'.
   `\\[ibuffer-mark-help-buffers]' - Mark buffers in `help-mode', `apropos-mode', etc.
   `\\[ibuffer-mark-old-buffers]' - Mark buffers older than `ibuffer-old-time'.
   `\\[ibuffer-mark-for-delete]' - Mark the buffer at point for deletion.
@@ -2639,17 +2635,17 @@ ibuffer-mode
 
 ** Information on Filtering:
 
- You can filter your ibuffer view via different criteria.  Each Ibuffer
+You can filter your Ibuffer view via different criteria.  Each Ibuffer
 buffer has its own stack of active filters.  For example, suppose you
 are working on an Emacs Lisp project.  You can create an Ibuffer
-buffer displays buffers in just `emacs-lisp' modes via
+buffer displaying only `emacs-lisp-mode' buffers via
 `\\[ibuffer-filter-by-mode] emacs-lisp-mode RET'.  In this case, there
 is just one entry on the filtering stack.
 
 You can also combine filters.  The various filtering commands push a
 new filter onto the stack, and the filters combine to show just
 buffers which satisfy ALL criteria on the stack.  For example, suppose
-you only want to see buffers in `emacs-lisp' mode, whose names begin
+you only want to see buffers in `emacs-lisp-mode', whose names begin
 with \"gnus\".  You can accomplish this via:
 
   \\[ibuffer-filter-by-mode] emacs-lisp-mode RET
@@ -2693,8 +2689,8 @@ ibuffer-mode
 multiple filter groups; instead, the first filter group is used.  The
 filter groups are displayed in this order of precedence.
 
-You may rearrange filter groups by using the regular
-`\\[ibuffer-kill-line]' and `\\[ibuffer-yank]' pair.  Yanked groups
+You may rearrange filter groups by using the usual pair
+`\\[ibuffer-kill-line]' and `\\[ibuffer-yank]'.  Yanked groups
 will be inserted before the group at point."
   ;; Include state info next to the mode name.
   (set (make-local-variable 'mode-line-process)
-- 
2.20.1


[-- Attachment #3: Type: text/plain, Size: 20 bytes --]


Thanks,

-- 
Basil

bug#35572: suggested improvement to ibuffer documentation

[Basil L. Contovounesios]

[Please keep the bug address CCed by using Reply To All or similar.]

Ed Mangimelli <ed.mangimelli@gmail.com> writes:

> Wow! Lot's of changes. Looks good to me, but I'm no elisp'er (or
> technical writer, for that matter).

Thanks for confirming.

Eli, are the documentation changes okay for emacs-26?  I'm thinking of
leaving the code parts alone for now, to be included in a larger
changeset for master I have on the back burner.

Thanks,

-- 
Basil

bug#35572: suggested improvement to ibuffer documentation

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Mon, 06 May 2019 02:49:07 +0100
> Cc: 35572@debbugs.gnu.org
> 
> Eli, are the documentation changes okay for emacs-26?

Yes.

bug#35572: suggested improvement to ibuffer documentation

[Basil L. Contovounesios]

tags 35572 fixed
close 35572 26.3
quit

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Mon, 06 May 2019 02:49:07 +0100
>> Cc: 35572@debbugs.gnu.org
>> 
>> Eli, are the documentation changes okay for emacs-26?
>
> Yes.

Thanks, I pushed them to emacs-26[1] and am therefore closing this
report.

[1: fb65a36f45]: Fix ibuffer-unmark-backward synopsis (bug#35572)
  2019-05-07 01:43:46 +0100
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=fb65a36f4587726b3de0df02daf02c28e9129f62

-- 
Basil