bug#73286: [PATCH] Add foldout command for widening to current fold

bug#73286: [PATCH] Add foldout command for widening to current fold

[Paul Nelson]

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

The foldout package, which "zooms in" on document sections by
narrowing the buffer, doesn't play well with Emacs's other narrowing
features: after narrowing further within a fold, there's no easy way
to widen back to the fold's boundaries.

This patch introduces foldout-widen-to-current-fold, a command that
widens to the current fold level (or to the whole buffer if not in a
fold).

Example usage:
- Use foldout-zoom-subtree to zoom in on some section.
- Use narrow-to-defun to edit some function.
- Use foldout-widen-to-current-fold to return to the scope of the
zoomed-in section.

Any feedback welcome.

Thanks, best,

Paul

[-- Attachment #2: 0001-Add-foldout-command-for-widening-to-current-fold.patch --]
[-- Type: application/octet-stream, Size: 3659 bytes --]

From 97e97799eb69e7339e24b4e6e2b2911cb32bc910 Mon Sep 17 00:00:00 2001
From: Paul Nelson <ultrono@gmail.com>
Date: Mon, 16 Sep 2024 01:33:53 +0200
Subject: [PATCH] Add foldout command for widening to current fold

* lisp/foldout.el (foldout-widen-to-current-fold): New command.
(foldout-inhibit-key-bindings): Bind it.
* doc/emacs/text.texi (Foldout): Document it.
* etc/NEWS: Announce it.
---
 doc/emacs/text.texi |  9 +++++++++
 etc/NEWS            |  8 ++++++++
 lisp/foldout.el     | 19 ++++++++++++++++++-
 3 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 9bc2a6407d5..6e304f3b8f6 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1396,6 +1396,15 @@ Foldout
 subheadings, specify a negative argument.  For example, @w{@kbd{M--2 C-c
 C-x}} exits two folds and leaves the text and subheadings exposed.
 
+@kindex C-x n w
+@findex foldout-widen-to-current-fold
+  While working within a fold, you may wish to use Emacs's standard
+narrowing commands such as @kbd{C-x n n} (@code{narrow-to-region}) or
+@kbd{C-x n d} (@code{narrow-to-defun}).  After using these commands,
+@kbd{C-c C-w} (@code{foldout-widen-to-current-fold}) allows you to
+widen back to the current fold level, rather than the entire buffer.
+If you're not currently in a fold, it behaves like @code{widen}.
+
   Foldout mode also provides mouse commands for entering and exiting
 folds, and for showing and hiding text:
 
diff --git a/etc/NEWS b/etc/NEWS
index 492159439fc..86a77f0b827 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -359,6 +359,14 @@ functionality of the standard 'xref' commands in TeX buffers.  You can
 restore the standard 'etags' backend with the 'M-x xref-etags-mode'
 toggle.
 
+** Foldout
+
+---
+*** New command 'foldout-widen-to-current-fold'.
+This command widens the view to the current fold level when in a fold,
+or behaves like 'widen' if not in a fold.  It's bound to 'C-w' in
+the Outline minor mode map.
+
 \f
 * New Modes and Packages in Emacs 31.1
 
diff --git a/lisp/foldout.el b/lisp/foldout.el
index 5799318fc6f..3c732e8b67c 100644
--- a/lisp/foldout.el
+++ b/lisp/foldout.el
@@ -490,6 +490,21 @@ foldout-mouse-goto-heading
       (error "Not a heading line")))
 \f
 
+(defun foldout-widen-to-current-fold ()
+  "Widen to the current fold level.
+If in a fold, widen to that fold's boundaries.
+If not in a fold, acts like `widen'."
+  (interactive)
+  (if foldout-fold-list
+      (let* ((last-fold (car foldout-fold-list))
+             (start (car last-fold))
+             (end (cdr last-fold)))
+        (widen)
+        (narrow-to-region start
+                          (if end (1- (marker-position end)) (point-max))))
+    (widen)))
+\f
+
 ;;; Keymaps:
 
 (defvar foldout-inhibit-key-bindings nil
@@ -506,12 +521,14 @@ foldout-mouse-modifiers
 (unless foldout-inhibit-key-bindings
   (define-key outline-mode-map "\C-c\C-z" #'foldout-zoom-subtree)
   (define-key outline-mode-map "\C-c\C-x" #'foldout-exit-fold)
+  (define-key outline-mode-map "\C-c\C-w" #'foldout-widen-to-current-fold)
   (let ((map (lookup-key outline-minor-mode-map outline-minor-mode-prefix)))
     (unless map
       (setq map (make-sparse-keymap))
       (define-key outline-minor-mode-map outline-minor-mode-prefix map))
     (define-key map "\C-z" #'foldout-zoom-subtree)
-    (define-key map "\C-x" #'foldout-exit-fold))
+    (define-key map "\C-x" #'foldout-exit-fold)
+    (define-key map "\C-w" #'foldout-widen-to-current-fold))
   (let* ((modifiers (apply #'concat
                            (mapcar (lambda (modifier)
                                      (vector
-- 
2.39.3 (Apple Git-145)

bug#73286: [PATCH] Add foldout command for widening to current fold

[Eli Zaretskii]

> From: Paul Nelson <ultrono@gmail.com>
> Date: Mon, 16 Sep 2024 01:38:35 +0200
> 
> The foldout package, which "zooms in" on document sections by
> narrowing the buffer, doesn't play well with Emacs's other narrowing
> features: after narrowing further within a fold, there's no easy way
> to widen back to the fold's boundaries.
> 
> This patch introduces foldout-widen-to-current-fold, a command that
> widens to the current fold level (or to the whole buffer if not in a
> fold).
> 
> Example usage:
> - Use foldout-zoom-subtree to zoom in on some section.
> - Use narrow-to-defun to edit some function.
> - Use foldout-widen-to-current-fold to return to the scope of the
> zoomed-in section.
> 
> Any feedback welcome.

Thanks.  This new feature LGTM, but I'm not convinced we should have a
separate key binding for this new command by default.  If we want to
have a default key binding at all, maybe we should make "C-c C-x"
invoke this command when given a negative argument.

Stefan and Andrea, WDYT?

bug#73286: [PATCH] Add foldout command for widening to current fold

[Paul Nelson]

> Thanks.  This new feature LGTM, but I'm not convinced we should have a
> separate key binding for this new command by default.  If we want to
> have a default key binding at all, maybe we should make "C-c C-x"
> invoke this command when given a negative argument.

Thanks.  Two quick comments:

1. I'm happy leaving the key unbound by default -- in my own config, I
rebind "C-x n w" from widen to foldout-widen-to-current-fold and never
use the proposed "C-c @ C-w" bind.

2. "C-c @ C-x" already treats negative arguments specially ("...with
ARG < 0, -ARG folds are exited and text is left visible")

bug#73286: [PATCH] Add foldout command for widening to current fold

[Andrea Corallo]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Paul Nelson <ultrono@gmail.com>
>> Date: Mon, 16 Sep 2024 01:38:35 +0200
>> 
>> The foldout package, which "zooms in" on document sections by
>> narrowing the buffer, doesn't play well with Emacs's other narrowing
>> features: after narrowing further within a fold, there's no easy way
>> to widen back to the fold's boundaries.
>> 
>> This patch introduces foldout-widen-to-current-fold, a command that
>> widens to the current fold level (or to the whole buffer if not in a
>> fold).
>> 
>> Example usage:
>> - Use foldout-zoom-subtree to zoom in on some section.
>> - Use narrow-to-defun to edit some function.
>> - Use foldout-widen-to-current-fold to return to the scope of the
>> zoomed-in section.
>> 
>> Any feedback welcome.
>
> Thanks.  This new feature LGTM, but I'm not convinced we should have a
> separate key binding for this new command by default.  If we want to
> have a default key binding at all, maybe we should make "C-c C-x"
> invoke this command when given a negative argument.
>
> Stefan and Andrea, WDYT?

I'm happy to have the feature in.  I guess we can introduce the
keybinding later in case it's requested.

  Andrea

bug#73286: [PATCH] Add foldout command for widening to current fold

[Stefan Kangas]

Andrea Corallo <acorallo@gnu.org> writes:

> I'm happy to have the feature in.  I guess we can introduce the
> keybinding later in case it's requested.

Agreed.

bug#73286: [PATCH] Add foldout command for widening to current fold

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Tue, 1 Oct 2024 21:33:32 +0200
> Cc: Paul Nelson <ultrono@gmail.com>, 73286@debbugs.gnu.org
> 
> Andrea Corallo <acorallo@gnu.org> writes:
> 
> > I'm happy to have the feature in.  I guess we can introduce the
> > keybinding later in case it's requested.
> 
> Agreed.

There seems to be a consensus to leave the command unbound, so Paul,
would you please submit a modified patch with that change?

Thanks.

bug#73286: [PATCH] Add foldout command for widening to current fold

[Paul Nelson]

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

> There seems to be a consensus to leave the command unbound, so Paul,
> would you please submit a modified patch with that change?
>
> Thanks.

Sure, please find attached.  Thanks for the feedback!  Paul

[-- Attachment #2: 0001-Add-foldout-command-for-widening-to-current-fold.patch --]
[-- Type: application/octet-stream, Size: 2663 bytes --]

From 0fff3f68f8b2f99c921025cc1cacd5310dc2e584 Mon Sep 17 00:00:00 2001
From: Paul Nelson <ultrono@gmail.com>
Date: Mon, 16 Sep 2024 01:33:53 +0200
Subject: [PATCH] Add foldout command for widening to current fold

* lisp/foldout.el (foldout-widen-to-current-fold): New command.
* doc/emacs/text.texi (Foldout): Document it.
* etc/NEWS: Announce it.
---
 doc/emacs/text.texi |  8 ++++++++
 etc/NEWS            |  7 +++++++
 lisp/foldout.el     | 15 +++++++++++++++
 3 files changed, 30 insertions(+)

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 9bc2a6407d5..a6d19a32bc5 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1396,6 +1396,14 @@ Foldout
 subheadings, specify a negative argument.  For example, @w{@kbd{M--2 C-c
 C-x}} exits two folds and leaves the text and subheadings exposed.
 
+@findex foldout-widen-to-current-fold
+  While working within a fold, you may wish to use Emacs's standard
+narrowing commands such as @kbd{C-x n n} (@code{narrow-to-region}) or
+@kbd{C-x n d} (@code{narrow-to-defun}).  After using these commands,
+@code{foldout-widen-to-current-fold}) allows you to widen back to the
+current fold level, rather than the entire buffer.  If you're not
+currently in a fold, it behaves like @code{widen}.
+
   Foldout mode also provides mouse commands for entering and exiting
 folds, and for showing and hiding text:
 
diff --git a/etc/NEWS b/etc/NEWS
index 492159439fc..6832753df43 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -359,6 +359,13 @@ functionality of the standard 'xref' commands in TeX buffers.  You can
 restore the standard 'etags' backend with the 'M-x xref-etags-mode'
 toggle.
 
+** Foldout
+
+---
+*** New command 'foldout-widen-to-current-fold'.
+This command widens the view to the current fold level when in a fold,
+or behaves like 'widen' if not in a fold.
+
 \f
 * New Modes and Packages in Emacs 31.1
 
diff --git a/lisp/foldout.el b/lisp/foldout.el
index 5799318fc6f..a4b6a402c5c 100644
--- a/lisp/foldout.el
+++ b/lisp/foldout.el
@@ -490,6 +490,21 @@ foldout-mouse-goto-heading
       (error "Not a heading line")))
 \f
 
+(defun foldout-widen-to-current-fold ()
+  "Widen to the current fold level.
+If in a fold, widen to that fold's boundaries.
+If not in a fold, acts like `widen'."
+  (interactive)
+  (if foldout-fold-list
+      (let* ((last-fold (car foldout-fold-list))
+             (start (car last-fold))
+             (end (cdr last-fold)))
+        (widen)
+        (narrow-to-region start
+                          (if end (1- (marker-position end)) (point-max))))
+    (widen)))
+\f
+
 ;;; Keymaps:
 
 (defvar foldout-inhibit-key-bindings nil
-- 
2.39.3 (Apple Git-145)

bug#73286: [PATCH] Add foldout command for widening to current fold

[Eli Zaretskii]

> From: Paul Nelson <ultrono@gmail.com>
> Date: Sat, 5 Oct 2024 12:14:57 +0100
> Cc: Stefan Kangas <stefankangas@gmail.com>, acorallo@gnu.org, 73286@debbugs.gnu.org
> 
> > There seems to be a consensus to leave the command unbound, so Paul,
> > would you please submit a modified patch with that change?
> >
> > Thanks.
> 
> Sure, please find attached.  Thanks for the feedback!  Paul

Thanks, installed on master, and closing the bug.