bug#31139: [PATCH] Document Narrow indicator in describe-mode

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Michael Hendricks]

* lisp/help.el (describe-mode): document narrowing, if active
---
 lisp/help.el | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lisp/help.el b/lisp/help.el
index 8e6604d2db..92a2f52d2d 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -908,6 +908,8 @@ documentation for the major and minor modes of that buffer."
 		   (push (list fmode pretty-minor-mode
 			       (format-mode-line (assq mode minor-mode-alist)))
 			 minor-modes)))))
+	(when (or (> (point-min) 1) (<= (point-max) (buffer-size)))
+	  (push '(narrow-to-region "Narrow" " Narrow") minor-modes))
 	(setq minor-modes
 	      (sort minor-modes
 		    (lambda (a b) (string-lessp (cadr a) (cadr b)))))
-- 
2.14.2

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Noam Postavsky]

severity 31139 wishlist
quit

Michael Hendricks <michael@ndrix.org> writes:

> * lisp/help.el (describe-mode): document narrowing, if active

> +	(when (or (> (point-min) 1) (<= (point-max) (buffer-size)))
> +	  (push '(narrow-to-region "Narrow" " Narrow") minor-modes))

Narrowing isn't exactly a minor mode though, wouldn't this be
potentially confusing?

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Michael Hendricks]

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

Hi Noam,

On Thu, Apr 12, 2018 at 5:36 PM Noam Postavsky <npostavs@gmail.com> wrote:

> Narrowing isn't exactly a minor mode though, wouldn't this be
> potentially confusing?
>

You're right that narrowing isn't exactly a minor mode.  However,
standard-mode-line-format includes narrowing information as part of
mode-line-modes.  So the narrowing indicator is rendered inside the same
parentheses as indicators for true major and minor modes.  Since
describe-mode provides documentation for everything else that's inside
those parentheses, it seemed appropriate to document narrowing in the same
place.

When I first started using emacs some years ago, I remember being confused
why "Narrow" was the only thing in the mode list that wasn't mentioned by
describe-mode.  I understand it now, but I think others might face similar
confusion with the current behavior.  I think this patch would address that.

[-- Attachment #2: Type: text/html, Size: 1373 bytes --]

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Noam Postavsky]

Michael Hendricks <michael@ndrix.org> writes:

> You're right that narrowing isn't exactly a minor mode.  However,
> standard-mode-line-format includes narrowing information as part of
> mode-line-modes.  So the narrowing indicator is rendered inside the
> same parentheses as indicators for true major and minor modes.  Since
> describe-mode provides documentation for everything else that's inside
> those parentheses, it seemed appropriate to document narrowing in the
> same place.

Okay, I'm convinced.  I think adding a comment along the lines of
"narrowing is not a minor mode, but its indicator is part of
mode-line-modes", would be helpful in case someone tries to "fix" your
change later.

> +	(when (or (> (point-min) 1) (<= (point-max) (buffer-size)))

You should use buffer-narrowed-p instead of checking point min & max
here.

Have you assigned copyright for Emacs? (the patch is small enough to
install regardless, I'm asking just to know if it should be marked as a
tiny change).

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Eli Zaretskii]

> From: Noam Postavsky <npostavs@gmail.com>
> Date: Thu, 19 Apr 2018 08:16:50 -0400
> Cc: 31139@debbugs.gnu.org
> 
> Have you assigned copyright for Emacs?

Not according to the current copyright assignment list.

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Michael Hendricks]

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

On Thu, Apr 19, 2018 at 6:16 AM Noam Postavsky <npostavs@gmail.com> wrote:

> Okay, I'm convinced.  I think adding a comment along the lines of
> "narrowing is not a minor mode, but its indicator is part of
> mode-line-modes", would be helpful in case someone tries to "fix" your
> change later.
>
> > +     (when (or (> (point-min) 1) (<= (point-max) (buffer-size)))
>
> You should use buffer-narrowed-p instead of checking point min & max
> here.
>

Sounds good.  I'll run Emacs with these changes over the weekend.  If
everything is solid, I'll reply with a final patch early next week.

Have you assigned copyright for Emacs?


I submitted my copyright assignment on April 11, 2018, but it sounds like
I'm not on the current copyright assignment list for some reason. I've cc'd
the FSF copyright clerk with whom I handled the assignment, in case he
knows what happened.  For reference, my RT number for the assignment
was 1287241.

[-- Attachment #2: Type: text/html, Size: 1627 bytes --]

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Eli Zaretskii]

> From: Michael Hendricks <michael@ndrix.org>
> Date: Thu, 19 Apr 2018 14:38:08 +0000
> Cc: 31139@debbugs.gnu.org, Eli Zaretskii <eliz@gnu.org>, 
> 	"copyright-clerk@fsf.org" <copyright-clerk@fsf.org>
> 
>  Have you assigned copyright for Emacs?
> 
> I submitted my copyright assignment on April 11, 2018, but it sounds like I'm not on the current copyright
> assignment list for some reason. I've cc'd the FSF copyright clerk with whom I handled the assignment, in
> case he knows what happened.  For reference, my RT number for the assignment was 1287241.

That means the assignment will come through in a few weeks.

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Michael Hendricks]

* lisp/help.el (describe-mode): document narrowing, if active
---
 lisp/help.el | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lisp/help.el b/lisp/help.el
index 8e6604d2db..844087a72f 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -908,6 +908,10 @@ documentation for the major and minor modes of that buffer."
 		   (push (list fmode pretty-minor-mode
 			       (format-mode-line (assq mode minor-mode-alist)))
 			 minor-modes)))))
+	;; Narrowing is not a minor mode, but its indicator is part of
+	;; mode-line-modes.
+	(when (buffer-narrowed-p)
+	  (push '(narrow-to-region "Narrow" " Narrow") minor-modes))
 	(setq minor-modes
 	      (sort minor-modes
 		    (lambda (a b) (string-lessp (cadr a) (cadr b)))))
-- 
2.14.2

bug#31139: [PATCH] Document Narrow indicator in describe-mode

[Eli Zaretskii]

> From: Michael Hendricks <michael@ndrix.org>
> Date: Tue, 24 Apr 2018 09:00:13 -0600
> Cc: Michael Hendricks <michael@ndrix.org>, Noam Postavsky <npostavs@gmail.com>
> 
> * lisp/help.el (describe-mode): document narrowing, if active
> ---
>  lisp/help.el | 4 ++++
>  1 file changed, 4 insertions(+)

Thanks, pushed to the master branch.