bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Stefan Kangas]

Severity: wishlist

Please consider adding two new commands to outline-mode similar to
org-cycle and org=global-cycle.

These are the suggested key bindings:

(define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
(define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)

They are already there in Org-mode and many users swear by them.
(In Org-mode, org-cycle is bound to TAB instead of C-TAB, but I don't
think that would work very well with outline-minor-mode.)

Background:
https://lists.gnu.org/archive/html/emacs-devel/2020-04/msg01887.html

These keybindings were first suggested by Howard Melman in the above
thread.

Best regards,
Stefan Kangas

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Stefan Kangas]

Stefan Kangas <stefankangas@gmail.com> writes:

> org-cycle and org=global-cycle.
                ^^^^^^^^^^^^^^^^
                should be `org-global-cycle', of course.

bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

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

Add two commands that cycles a heading (like that in Org mode) in outline-mode:

- outline-cycle: cycles between “hide all”, “sub headings” and “show all” state. They are called “FOLDED”, “CHILDREN”, “SUBTREE” in Org mode. 
- outline-cycle-buffer: cycles between “only top level headings”, “all headings”, “show all” states

Could this be useful?

Yuan


[-- Attachment #2: outline.patch --]
[-- Type: application/octet-stream, Size: 3350 bytes --]

diff --git a/lisp/outline.el b/lisp/outline.el
index 28ea8a86e6..99a24deed0 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1118,6 +1118,77 @@ outline-headers-as-kill
                     (insert "\n\n"))))))
           (kill-new (buffer-string)))))))
 
+(defun outline--cycle-state ()
+  "Return the cycle state of current heading.
+Return either 'hide-all, 'headings-only, or 'show-all."
+  (save-excursion
+    (let (start end ov-list heading-end)
+      (outline-back-to-heading)
+      (setq start (point))
+      (outline-end-of-heading)
+      (setq heading-end (point))
+      (outline-end-of-subtree)
+      (setq end (point))
+      (setq ov-list (cl-remove-if-not
+                     (lambda (o) (eq (overlay-get o 'invisible) 'outline))
+                     (overlays-in start end)))
+      (cond ((eq ov-list nil) 'show-all)
+            ;; (eq (length ov-list) 1) wouldn’t work: what if there is
+            ;; one folded subheading?
+            ((and (eq (overlay-end (car ov-list)) end)
+                  (eq (overlay-start (car ov-list)) heading-end))
+             'hide-all)
+            (t 'headings-only)))))
+
+(defun outline-has-subheading-p ()
+  "Return t if this heading has subheadings, nil otherwise."
+  (save-excursion
+    (outline-back-to-heading)
+    (< (save-excursion (outline-next-heading) (point))
+       (save-excursion (outline-end-of-subtree) (point)))))
+
+(defun outline-cycle ()
+  "Cycle between “hide all”, “headings only” and “show all”.
+
+“Hide all” means hide all subheadings and their bodies.
+“Headings only” means show sub headings but not their bodies.
+“Show all” means show all subheadings and their bodies."
+  (interactive)
+  (pcase (outline--cycle-state)
+    ('hide-all (if (outline-has-subheading-p)
+                   (progn (outline-show-children)
+                          (message "Only headings"))
+                 (outline-show-subtree)
+                 (message "Show all")))
+    ('headings-only (outline-show-subtree)
+                    (message "Show all"))
+    ('show-all (outline-hide-subtree)
+               (message "Hide all"))))
+
+(defvar-local outline--cycle-buffer-state 'show-all
+  "Interval variable used for tracking buffer cycle state.")
+
+(defun outline-cycle-buffer ()
+  "Cycle the whole buffer like in ‘outline-cycle’."
+  (interactive)
+  (pcase outline--cycle-buffer-state
+    ('show-all (save-excursion
+                 (let ((start-point (point)))
+                   (while (not (eq (point) start-point))
+                     (outline-up-heading 1))
+                   (outline-hide-sublevels
+                    (progn (outline-back-to-heading)
+                           (funcall 'outline-level)))))
+               (setq outline--cycle-buffer-state 'top-level)
+               (message "Top level headings"))
+    ('top-level (outline-show-all)
+                (outline-hide-region-body (point-min) (point-max))
+                (setq outline--cycle-buffer-state 'all-heading)
+                (message "All headings"))
+    ('all-heading (outline-show-all)
+                  (setq outline--cycle-buffer-state 'show-all)
+                  (message "Show all"))))
+
 (provide 'outline)
 (provide 'noutline)
 

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

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Juri Linkov]

> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>
> They are already there in Org-mode and many users swear by them.
> (In Org-mode, org-cycle is bound to TAB instead of C-TAB, but I don't
> think that would work very well with outline-minor-mode.)

C-TAB switches tabs in tab-bar-mode.

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Tassilo Horn]

Stefan Kangas <stefankangas@gmail.com> writes:

> Severity: wishlist
>
> Please consider adding two new commands to outline-mode similar to
> org-cycle and org=global-cycle.

I'm also very much in favor of this.  I think probably every user has
his own incarnation of such a command.

> These are the suggested key bindings:
>
> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)

Well, I think those shouldn't be commands in outline-minor-mode-map as
they should only be active when point is on an outline heading, no?  At
least that's the case with org-mode where TAB acts quite differently
depending on the context.

So that's my personal incarnation:

--8<---------------cut here---------------start------------->8---
(defmacro th/define-context-key (keymap key dispatch)
  "Define KEY in KEYMAP to execute according to DISPATCH.

DISPATCH is a form that is evaluated and should return the
command to be executed.

If DISPATCH returns nil, then the command normally bound to KEY
will be executed.

Example:

  (th/define-context-key hs-minor-mode-map
     (kbd \"<C-tab>\")
     (cond
      ((not (hs-already-hidden-p))
       'hs-hide-block)
      ((hs-already-hidden-p)
       'hs-show-block)))

This will make <C-tab> show a hidden block.  If the block is
shown, then it'll be hidden."
  (declare (indent 2))
  `(define-key ,keymap ,key
     `(menu-item "context-key" ignore
                 :filter ,(lambda (&optional ignored)
                            ,dispatch))))

(th/define-context-key outline-minor-mode-map (kbd "<tab>")
    (when (save-excursion
            (move-beginning-of-line 1)
            (looking-at-p outline-regexp))
      'outline-toggle-children))
--8<---------------cut here---------------end--------------->8---

Of course, outline-toggle-children is not exactly like org-cycle or
org-global-cycle but it gets the job done.

Bye,
Tassilo

PS: On a related note, I think there should be some standard facility
for defining keys depending on the context.  If Stefan hadn't shown me
the menu-item-with-:filter trick some years ago, I would probably not
found out myself.

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Robert Pluim]

>>>>> On Wed, 13 May 2020 09:13:14 +0200, Tassilo Horn <tsdh@gnu.org> said:

    Tassilo> PS: On a related note, I think there should be some standard facility
    Tassilo> for defining keys depending on the context.  If Stefan hadn't shown me
    Tassilo> the menu-item-with-:filter trick some years ago, I would probably not
    Tassilo> found out myself.

You can set a 'keymap property on buffer text. Of course then you have
to make sure that the property is kept up to date....

Robert

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Tassilo Horn]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Wed, 13 May 2020 09:13:14 +0200, Tassilo Horn <tsdh@gnu.org> said:
>
>     Tassilo> PS: On a related note, I think there should be some
>     Tassilo> standard facility for defining keys depending on the
>     Tassilo> context.  If Stefan hadn't shown me the
>     Tassilo> menu-item-with-:filter trick some years ago, I would
>     Tassilo> probably not found out myself.
>
> You can set a 'keymap property on buffer text. Of course then you have
> to make sure that the property is kept up to date....

Yes, that's not something which could be done easily for users.  And it
restricts dispatch to where point is on.  FWIW, in my uses of
th/define-context-key I also dispatch on the syntax at point or even
last-command-event in order to do something else when hitting the key
twice.

Anyway, I don't want to hijack this bug report.

Bye,
Tassilo

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Stefan Kangas]

forcemerge 41130 41198
thanks

Yuan Fu <casouri@gmail.com> writes:

> Add two commands that cycles a heading (like that in Org mode) in outline-mode:
>
> - outline-cycle: cycles between “hide all”, “sub headings” and “show all” state. They are called “FOLDED”, “CHILDREN”, “SUBTREE” in Org mode.
> - outline-cycle-buffer: cycles between “only top level headings”, “all headings”, “show all” states

Thanks for working on this.  I've tested your patch, and it seems to
work as advertised.

> Could this be useful?

I think it could.  I have previously sent the wishlist Bug#41130, which
I have now merged with this bug.  I have seen no objections to that
proposal, so I hope that it is uncontroversial.

In Bug#41130, I also suggest to add the same keybinding as in org-mode:
TAB and S-TAB.  Could you add such keybindings to outline-mode-map in
your patch?

I think we also need ChangeLog in the commit message, an entry in NEWS,
and updates to the manual.

> +(defun outline-cycle ()
> +  "Cycle between “hide all”, “headings only” and “show all”.
> +
> +“Hide all” means hide all subheadings and their bodies.
> +“Headings only” means show sub headings but not their bodies.
> +“Show all” means show all subheadings and their bodies."

I can't remember seeing double quotes used like that before in doc
strings.  Correct me if I'm wrong, but wouldn't we normally use
`single-quotes' for something like this?

Best regards,
Stefan Kangas

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

>> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>>
>> They are already there in Org-mode and many users swear by them.
>> (In Org-mode, org-cycle is bound to TAB instead of C-TAB, but I don't
>> think that would work very well with outline-minor-mode.)
>
> C-TAB switches tabs in tab-bar-mode.

Sorry, it seems I wrote this bug report in a very confusing way.
Please let me try again.

One part would be to add:

    (define-key outline-mode-map (kbd "<tab>") 'outline-cycle)
    (define-key outline-mode-map (kbd "S-<tab>") 'outline-global-cycle)

I also think we should also consider:

    (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
    (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)

If there is a conflict with tab-bar-mode on C-TAB, maybe we could use
M-TAB instead?

Best regards,
Stefan Kangas

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Stefan Kangas]

Tassilo Horn <tsdh@gnu.org> writes:

> I'm also very much in favor of this.  I think probably every user has
> his own incarnation of such a command.

I wish I was one of these users.  ;-)

> Well, I think those shouldn't be commands in outline-minor-mode-map as
> they should only be active when point is on an outline heading, no?  At
> least that's the case with org-mode where TAB acts quite differently
> depending on the context.

This is a good point, yes.

> --8<---------------cut here---------------start------------->8---
> (defmacro th/define-context-key (keymap key dispatch)
>   "Define KEY in KEYMAP to execute according to DISPATCH.
>
> DISPATCH is a form that is evaluated and should return the
> command to be executed.
>
> If DISPATCH returns nil, then the command normally bound to KEY
> will be executed.
>
> Example:
>
>   (th/define-context-key hs-minor-mode-map
>      (kbd \"<C-tab>\")
>      (cond
>       ((not (hs-already-hidden-p))
>        'hs-hide-block)
>       ((hs-already-hidden-p)
>        'hs-show-block)))
>
> This will make <C-tab> show a hidden block.  If the block is
> shown, then it'll be hidden."
>   (declare (indent 2))
>   `(define-key ,keymap ,key
>      `(menu-item "context-key" ignore
>                  :filter ,(lambda (&optional ignored)
>                             ,dispatch))))
>
> (th/define-context-key outline-minor-mode-map (kbd "<tab>")
>     (when (save-excursion
>             (move-beginning-of-line 1)
>             (looking-at-p outline-regexp))
>       'outline-toggle-children))
> --8<---------------cut here---------------end--------------->8---

Interesting.  I suppose the only question I have is this: how do we turn
this into something we could add to Emacs?

There is also the question of C-TAB conflicting with tab-bar-mode.

> PS: On a related note, I think there should be some standard facility
> for defining keys depending on the context.  If Stefan hadn't shown me
> the menu-item-with-:filter trick some years ago, I would probably not
> found out myself.

Agreed.  I had not seen that before, until now.

Best regards,
Stefan Kangas

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

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



> On May 18, 2020, at 10:45 PM, Stefan Kangas <stefan@marxist.se> wrote:
> 
> forcemerge 41130 41198
> thanks
> 
> Yuan Fu <casouri@gmail.com> writes:
> 
>> Add two commands that cycles a heading (like that in Org mode) in outline-mode:
>> 
>> - outline-cycle: cycles between “hide all”, “sub headings” and “show all” state. They are called “FOLDED”, “CHILDREN”, “SUBTREE” in Org mode.
>> - outline-cycle-buffer: cycles between “only top level headings”, “all headings”, “show all” states
> 
> Thanks for working on this.  I've tested your patch, and it seems to
> work as advertised.

Thanks.

> 
>> Could this be useful?
> 
> I think it could.  I have previously sent the wishlist Bug#41130, which
> I have now merged with this bug.  I have seen no objections to that
> proposal, so I hope that it is uncontroversial.
> 
> In Bug#41130, I also suggest to add the same keybinding as in org-mode:
> TAB and S-TAB.  Could you add such keybindings to outline-mode-map in
> your patch?

It seems that the outline-mode bindings all live under C-c. Maybe C-c TAB and C-c S-TAB? Should I ask on emacs-devel for for suggestions?

> 
> I think we also need ChangeLog in the commit message, an entry in NEWS,
> and updates to the manual.

I updated NEWS and the manual. For ChangeLog, I thought that’s automatically generated from commit messages?

> 
>> +(defun outline-cycle ()
>> +  "Cycle between “hide all”, “headings only” and “show all”.
>> +
>> +“Hide all” means hide all subheadings and their bodies.
>> +“Headings only” means show sub headings but not their bodies.
>> +“Show all” means show all subheadings and their bodies."
> 
> I can't remember seeing double quotes used like that before in doc
> strings.  Correct me if I'm wrong, but wouldn't we normally use
> `single-quotes' for something like this?
> 

Done.

Yuan


[-- Attachment #2: outline.patch --]
[-- Type: application/octet-stream, Size: 4733 bytes --]

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 281e24421c..e2f829b7c5 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1207,6 +1207,15 @@ Outline Visibility
 it completely reveals all the @var{n} top levels and the body lines
 before the first heading.
 
+@findex outline-cycle
+@findex outline-cycle-buffer
+  Outline also provides two convenience commands to cycle the
+visibility of each heading and the whole buffer.  @code{outline-cycle}
+cycles the current heading between "hide all", "subheadings", and
+"show all" state.  @code{outline-cycle-buffer} cycles the whole buffer
+between "only top-level headings", "all headings and subheadings", and
+"show all" states.
+
 @anchor{Outline Search}
 @findex reveal-mode
 @vindex search-invisible
diff --git a/etc/NEWS b/etc/NEWS
index 025d5c14a7..3ecec6d0e4 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -288,6 +288,14 @@ prefix on the Subject line in various languages.
 These new navigation commands are bound to 'n' and 'p' in
 'apropos-mode'.
 
+** Outline
+
+*** New commands to cycle heading visibility.
+'outline-cycle' cycles the current heading between "hide all",
+"subheadings", and "show all" state. 'outline-cycle-buffer' cycles the
+whole buffer between "only top-level headings", "all headings and
+subheadings", and "show all" states.
+
 \f
 * New Modes and Packages in Emacs 28.1
 
diff --git a/lisp/outline.el b/lisp/outline.el
index 28ea8a86e6..8dd1b4483c 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1118,6 +1118,77 @@ outline-headers-as-kill
                     (insert "\n\n"))))))
           (kill-new (buffer-string)))))))
 
+(defun outline--cycle-state ()
+  "Return the cycle state of current heading.
+Return either 'hide-all, 'headings-only, or 'show-all."
+  (save-excursion
+    (let (start end ov-list heading-end)
+      (outline-back-to-heading)
+      (setq start (point))
+      (outline-end-of-heading)
+      (setq heading-end (point))
+      (outline-end-of-subtree)
+      (setq end (point))
+      (setq ov-list (cl-remove-if-not
+                     (lambda (o) (eq (overlay-get o 'invisible) 'outline))
+                     (overlays-in start end)))
+      (cond ((eq ov-list nil) 'show-all)
+            ;; (eq (length ov-list) 1) wouldn’t work: what if there is
+            ;; one folded subheading?
+            ((and (eq (overlay-end (car ov-list)) end)
+                  (eq (overlay-start (car ov-list)) heading-end))
+             'hide-all)
+            (t 'headings-only)))))
+
+(defun outline-has-subheading-p ()
+  "Return t if this heading has subheadings, nil otherwise."
+  (save-excursion
+    (outline-back-to-heading)
+    (< (save-excursion (outline-next-heading) (point))
+       (save-excursion (outline-end-of-subtree) (point)))))
+
+(defun outline-cycle ()
+  "Cycle between `hide all', `headings only' and `show all'.
+
+`Hide all' means hide all subheadings and their bodies.
+`Headings only' means show sub headings but not their bodies.
+`Show all' means show all subheadings and their bodies."
+  (interactive)
+  (pcase (outline--cycle-state)
+    ('hide-all (if (outline-has-subheading-p)
+                   (progn (outline-show-children)
+                          (message "Only headings"))
+                 (outline-show-subtree)
+                 (message "Show all")))
+    ('headings-only (outline-show-subtree)
+                    (message "Show all"))
+    ('show-all (outline-hide-subtree)
+               (message "Hide all"))))
+
+(defvar-local outline--cycle-buffer-state 'show-all
+  "Internal variable used for tracking buffer cycle state.")
+
+(defun outline-cycle-buffer ()
+  "Cycle the whole buffer like in `outline-cycle'."
+  (interactive)
+  (pcase outline--cycle-buffer-state
+    ('show-all (save-excursion
+                 (let ((start-point (point)))
+                   (while (not (eq (point) start-point))
+                     (outline-up-heading 1))
+                   (outline-hide-sublevels
+                    (progn (outline-back-to-heading)
+                           (funcall 'outline-level)))))
+               (setq outline--cycle-buffer-state 'top-level)
+               (message "Top level headings"))
+    ('top-level (outline-show-all)
+                (outline-hide-region-body (point-min) (point-max))
+                (setq outline--cycle-buffer-state 'all-heading)
+                (message "All headings"))
+    ('all-heading (outline-show-all)
+                  (setq outline--cycle-buffer-state 'show-all)
+                  (message "Show all"))))
+
 (provide 'outline)
 (provide 'noutline)
 

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Juri Linkov]

>>> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>>> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>>>
>>> They are already there in Org-mode and many users swear by them.
>>> (In Org-mode, org-cycle is bound to TAB instead of C-TAB, but I don't
>>> think that would work very well with outline-minor-mode.)
>>
>> C-TAB switches tabs in tab-bar-mode.
>
> Sorry, it seems I wrote this bug report in a very confusing way.
> Please let me try again.
>
> One part would be to add:
>
>     (define-key outline-mode-map (kbd "<tab>") 'outline-cycle)
>     (define-key outline-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>
> I also think we should also consider:
>
>     (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>     (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>
> If there is a conflict with tab-bar-mode on C-TAB, maybe we could use
> M-TAB instead?

M-TAB switches desktop windows in many window managers.

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Stefan Kangas]

Yuan Fu <casouri@gmail.com> writes:

>> In Bug#41130, I also suggest to add the same keybinding as in org-mode:
>> TAB and S-TAB.  Could you add such keybindings to outline-mode-map in
>> your patch?
>
> It seems that the outline-mode bindings all live under C-c. Maybe C-c
> TAB and C-c S-TAB? Should I ask on emacs-devel for for suggestions?

I think it is better to use the same keys as org-mode, since one
important motivation for this feature is precisely to align the
outline-mode keybindings with org-mode.  This aspect would be
significantly diminished by using other keys, IMHO.

My impression was that also there was consensus around (or at least no
objections to) that idea the last time we discussed it.  I would
therefore propose to just add TAB and S-TAB to the patch, but allow a
week or two before pushing to give others a chance to comment here.

But, if you really want to, of course you could also ask on emacs-devel.
Worst case, we get to have another round of bikeshedding. ;-)

>> I think we also need ChangeLog in the commit message, an entry in NEWS,
>> and updates to the manual.
>
> I updated NEWS and the manual. For ChangeLog, I thought that’s
> automatically generated from commit messages?

That is my understanding too.

But I only saw a diff attached, not a patch with a commit message.  That
is what I tried to say, but I could've been more clear.

(CONTRIBUTE suggests using `git format-patch -1' to email a patch, which
includes the commit message.)

> +@findex outline-cycle
> +@findex outline-cycle-buffer
> +  Outline also provides two convenience commands to cycle the
> +visibility of each heading and the whole buffer.  @code{outline-cycle}
> +cycles the current heading between "hide all", "subheadings", and
> +"show all" state.  @code{outline-cycle-buffer} cycles the whole buffer
> +between "only top-level headings", "all headings and subheadings", and
> +"show all" states.
[...]
> +*** New commands to cycle heading visibility.
> +'outline-cycle' cycles the current heading between "hide all",
> +"subheadings", and "show all" state. 'outline-cycle-buffer' cycles the
> +whole buffer between "only top-level headings", "all headings and
> +subheadings", and "show all" states.

Looks good to me (but should refer to the above keybindings if they're
added).

Best regards,
Stefan Kangas

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

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



> On May 19, 2020, at 6:36 PM, Stefan Kangas <stefan@marxist.se> wrote:
> 
> Yuan Fu <casouri@gmail.com> writes:
> 
>>> In Bug#41130, I also suggest to add the same keybinding as in org-mode:
>>> TAB and S-TAB.  Could you add such keybindings to outline-mode-map in
>>> your patch?
>> 
>> It seems that the outline-mode bindings all live under C-c. Maybe C-c
>> TAB and C-c S-TAB? Should I ask on emacs-devel for for suggestions?
> 
> I think it is better to use the same keys as org-mode, since one
> important motivation for this feature is precisely to align the
> outline-mode keybindings with org-mode.  This aspect would be
> significantly diminished by using other keys, IMHO.
> 
> My impression was that also there was consensus around (or at least no
> objections to) that idea the last time we discussed it.  I would
> therefore propose to just add TAB and S-TAB to the patch, but allow a
> week or two before pushing to give others a chance to comment here.
> 
> But, if you really want to, of course you could also ask on emacs-devel.
> Worst case, we get to have another round of bikeshedding. ;-)

I added TAB and S-TAB bindings. Though S-TAB appears to be <backtab> on my machine (Mac) for both terminal and GUI so I bound that instead. Is that so for other machines? To reduce the possible allergy, I made the TAB binding conditional—only invokes outline-cycle when point is on a heading.

A minor thing: if the motivation is to align with Org mode, should I change the text message to align with Org mode? It prints “show all”, “hide all”, etc (because they make sense), but Org mode prints stuff like “CHILDREN”, “SUBTREE”, etc.

> 
>>> I think we also need ChangeLog in the commit message, an entry in NEWS,
>>> and updates to the manual.
>> 
>> I updated NEWS and the manual. For ChangeLog, I thought that’s
>> automatically generated from commit messages?
> 
> That is my understanding too.
> 
> But I only saw a diff attached, not a patch with a commit message.  That
> is what I tried to say, but I could've been more clear.
> 
> (CONTRIBUTE suggests using `git format-patch -1' to email a patch, which
> includes the commit message.)

Ah sorry, I switched to a new way to generate patches and didn’t notice that the commit message is gone. It is included this time.

> 
>> +@findex outline-cycle
>> +@findex outline-cycle-buffer
>> +  Outline also provides two convenience commands to cycle the
>> +visibility of each heading and the whole buffer.  @code{outline-cycle}
>> +cycles the current heading between "hide all", "subheadings", and
>> +"show all" state.  @code{outline-cycle-buffer} cycles the whole buffer
>> +between "only top-level headings", "all headings and subheadings", and
>> +"show all" states.
> [...]
>> +*** New commands to cycle heading visibility.
>> +'outline-cycle' cycles the current heading between "hide all",
>> +"subheadings", and "show all" state. 'outline-cycle-buffer' cycles the
>> +whole buffer between "only top-level headings", "all headings and
>> +subheadings", and "show all" states.
> 
> Looks good to me (but should refer to the above keybindings if they're
> added).

Yuan


[-- Attachment #2: outline.patch --]
[-- Type: application/octet-stream, Size: 6151 bytes --]

From 243d6dec5c33c7add2fd12fe0da3e49a134cf0a9 Mon Sep 17 00:00:00 2001
From: Yuan Fu <casouri@gmail.com>
Date: Sun, 10 May 2020 17:10:32 -0400
Subject: [PATCH] Add cycling commands to outline

* lisp/outline.el (outline--cycle-state, outline-has-subheading-p,
outline-cycle, outline-cycle-buffer): New functions.
(outline-mode-map): Add key bindings for the two new commands.
(outline--cycle-buffer-state): New variable.
* doc/emacs/text.text (Outline Visibility): Add 'outline-cycle' and
'outline-cycle-buffer'.
* etc/NEWS (Outline): Record the change.
---
 doc/emacs/text.texi | 10 ++++++
 etc/NEWS            |  9 ++++++
 lisp/outline.el     | 77 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 96 insertions(+)

diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi
index 281e24421c..9c2822ce15 100644
--- a/doc/emacs/text.texi
+++ b/doc/emacs/text.texi
@@ -1207,6 +1207,16 @@ Outline Visibility
 it completely reveals all the @var{n} top levels and the body lines
 before the first heading.
 
+@findex outline-cycle
+@findex outline-cycle-buffer
+  Outline also provides two convenience commands to cycle the
+visibility of each section and the whole buffer.  Typing @kbd{TAB} on
+a heading invokes @code{outline-cycle}, which cycles the current
+section between "hide all", "subheadings", and "show all" state.
+Typing @kbd{S-TAB} invokes @code{outline-cycle-buffer}, which cycles
+the whole buffer between "only top-level headings", "all headings and
+subheadings", and "show all" states.
+
 @anchor{Outline Search}
 @findex reveal-mode
 @vindex search-invisible
diff --git a/etc/NEWS b/etc/NEWS
index 025d5c14a7..72057af94d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -288,6 +288,15 @@ prefix on the Subject line in various languages.
 These new navigation commands are bound to 'n' and 'p' in
 'apropos-mode'.
 
+** Outline
+
+*** New commands to cycle heading visibility
+
+Typing 'TAB' on a heading cycles the current section between "hide
+all", "subheadings", and "show all" state. Typing 'S-TAB' anywhere in
+the buffer cycles the whole buffer between "only top-level headings",
+"all headings and subheadings", and "show all" states.
+
 \f
 * New Modes and Packages in Emacs 28.1
 
diff --git a/lisp/outline.el b/lisp/outline.el
index 28ea8a86e6..0d792dd28c 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -179,6 +179,12 @@ outline-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key map "\C-c" outline-mode-prefix-map)
     (define-key map [menu-bar] outline-mode-menu-bar-map)
+    ;; Only takes effect if the point is on a heading.
+    (define-key map (kbd "TAB")
+      `(menu-item "" outline-cycle
+                  :filter ,(lambda (cmd)
+                             (when (outline-on-heading-p) cmd))))
+    (define-key map (kbd "<backtab>") #'outline-cycle-buffer)
     map))
 
 (defvar outline-font-lock-keywords
@@ -1118,6 +1124,77 @@ outline-headers-as-kill
                     (insert "\n\n"))))))
           (kill-new (buffer-string)))))))
 
+(defun outline--cycle-state ()
+  "Return the cycle state of current heading.
+Return either 'hide-all, 'headings-only, or 'show-all."
+  (save-excursion
+    (let (start end ov-list heading-end)
+      (outline-back-to-heading)
+      (setq start (point))
+      (outline-end-of-heading)
+      (setq heading-end (point))
+      (outline-end-of-subtree)
+      (setq end (point))
+      (setq ov-list (cl-remove-if-not
+                     (lambda (o) (eq (overlay-get o 'invisible) 'outline))
+                     (overlays-in start end)))
+      (cond ((eq ov-list nil) 'show-all)
+            ;; (eq (length ov-list) 1) wouldn’t work: what if there is
+            ;; one folded subheading?
+            ((and (eq (overlay-end (car ov-list)) end)
+                  (eq (overlay-start (car ov-list)) heading-end))
+             'hide-all)
+            (t 'headings-only)))))
+
+(defun outline-has-subheading-p ()
+  "Return t if this heading has subheadings, nil otherwise."
+  (save-excursion
+    (outline-back-to-heading)
+    (< (save-excursion (outline-next-heading) (point))
+       (save-excursion (outline-end-of-subtree) (point)))))
+
+(defun outline-cycle ()
+  "Cycle between `hide all', `headings only' and `show all'.
+
+`Hide all' means hide all subheadings and their bodies.
+`Headings only' means show sub headings but not their bodies.
+`Show all' means show all subheadings and their bodies."
+  (interactive)
+  (pcase (outline--cycle-state)
+    ('hide-all (if (outline-has-subheading-p)
+                   (progn (outline-show-children)
+                          (message "Only headings"))
+                 (outline-show-subtree)
+                 (message "Show all")))
+    ('headings-only (outline-show-subtree)
+                    (message "Show all"))
+    ('show-all (outline-hide-subtree)
+               (message "Hide all"))))
+
+(defvar-local outline--cycle-buffer-state 'show-all
+  "Internal variable used for tracking buffer cycle state.")
+
+(defun outline-cycle-buffer ()
+  "Cycle the whole buffer like in `outline-cycle'."
+  (interactive)
+  (pcase outline--cycle-buffer-state
+    ('show-all (save-excursion
+                 (let ((start-point (point)))
+                   (while (not (eq (point) start-point))
+                     (outline-up-heading 1))
+                   (outline-hide-sublevels
+                    (progn (outline-back-to-heading)
+                           (funcall 'outline-level)))))
+               (setq outline--cycle-buffer-state 'top-level)
+               (message "Top level headings"))
+    ('top-level (outline-show-all)
+                (outline-hide-region-body (point-min) (point-max))
+                (setq outline--cycle-buffer-state 'all-heading)
+                (message "All headings"))
+    ('all-heading (outline-show-all)
+                  (setq outline--cycle-buffer-state 'show-all)
+                  (message "Show all"))))
+
 (provide 'outline)
 (provide 'noutline)
 
-- 
2.26.1


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

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Howard Melman]

Yuan Fu <casouri@gmail.com> writes:

>> On May 19, 2020, at 6:36 PM, Stefan Kangas <stefan@marxist.se> wrote:
>> 
>> Yuan Fu <casouri@gmail.com> writes:
>> 
>>>> In Bug#41130, I also suggest to add the same keybinding as in org-mode:
>>>> TAB and S-TAB.  Could you add such keybindings to outline-mode-map in
>>>> your patch?
>>> 
>>> It seems that the outline-mode bindings all live under C-c. Maybe C-c
>>> TAB and C-c S-TAB? Should I ask on emacs-devel for for suggestions?
>> 
>> I think it is better to use the same keys as org-mode, since one
>> important motivation for this feature is precisely to align the
>> outline-mode keybindings with org-mode.  This aspect would be
>> significantly diminished by using other keys, IMHO.
>> 
>> My impression was that also there was consensus around (or at least no
>> objections to) that idea the last time we discussed it.  I would
>> therefore propose to just add TAB and S-TAB to the patch, but allow a
>> week or two before pushing to give others a chance to comment here.

My original motivation was just to use org's cycling concept
to avoid having to remember all of outlines various commands
and bindings. So regardless of where these commands end up,
I think just having them is a big win. Of course if they
exist, aligning them with org bindings would be very nice.

The idea was to use this for code folding in programming
modes. S-TAB doesn't typically have a binding so it's safe
to use and aligns with org-mode.  

TAB is more problematic as it's typically bound to indenting
commands. I don't think context awareness would solve the
issue as you could want to indent or cycle when point is on
a "heading".  But if the other bindings (I think from
bug#41198) for M-right and M-left were included they could
substitute for indenting.

So in a programming mode with outline-minor-mode enabled:
- S-TAB can be used anywhere for global cycling
- TAB on a heading is used for cycling
- TAB not on a heading is used to indent
- M-right and M-left anywhere can be used to indent/unindent

I think this aligns with org-mode ('m not an org mode
user). If someone is bothered by having to use M-arrows for
indentation in this case, the answer is to not use
outline-minor-mode in a programming mode or rebind outline-cycle.

> A minor thing: if the motivation is to align with Org mode, should I
> change the text message to align with Org mode? It prints “show all”,
> “hide all”, etc (because they make sense), but Org mode prints stuff
> like “CHILDREN”, “SUBTREE”, etc.

IMHO consistency with outline terms is more important
here. It would be helpful if outline and org agreed on
terms. If they don't, then perhaps this could use both with
org terms in parenthesis.

-- 

Howard

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Stefan Kangas]

Howard Melman <hmelman@gmail.com> writes:

> So in a programming mode with outline-minor-mode enabled:
> - S-TAB can be used anywhere for global cycling
> - TAB on a heading is used for cycling
> - TAB not on a heading is used to indent
> - M-right and M-left anywhere can be used to indent/unindent

Thanks.

I think what you say makes sense for outline-minor-mode.  We should take
care to distinguish that case from outline-mode, however.

>> A minor thing: if the motivation is to align with Org mode, should I
>> change the text message to align with Org mode? It prints “show all”,
>> “hide all”, etc (because they make sense), but Org mode prints stuff
>> like “CHILDREN”, “SUBTREE”, etc.
>
> IMHO consistency with outline terms is more important
> here. It would be helpful if outline and org agreed on
> terms. If they don't, then perhaps this could use both with
> org terms in parenthesis.

I think outline-mode should also be internally consistent with itself.
So I would suggest to stick to whatever terminology outline-mode uses
elsewhere also for these commands.

Maybe this suggests that the terminology in org-mode and outline-mode
could be aligned also on this point?  But that seems to be a different
issue than the one at hand.

Best regards,
Stefan Kangas

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Bastien]

Stefan Kangas <stefankangas@gmail.com> writes:

> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
                                           ^^^^^^^

Why not just <tab>, when point is on an outline entry?

-- 
 Bastien

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Bastien]

Juri Linkov <juri@linkov.net> writes:

>> If there is a conflict with tab-bar-mode on C-TAB, maybe we could use
>> M-TAB instead?
>
> M-TAB switches desktop windows in many window managers.

Indeed.  I suggest using C-M-tab.

`org-force-cycle-archived' is not so used IMHO.

-- 
 Bastien

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Eli Zaretskii]

> From: Bastien <bzg@gnu.org>
> Date: Sun, 24 May 2020 09:29:41 +0200
> Cc: Stefan Kangas <stefan@marxist.se>, 41130@debbugs.gnu.org
> 
> Juri Linkov <juri@linkov.net> writes:
> 
> >> If there is a conflict with tab-bar-mode on C-TAB, maybe we could use
> >> M-TAB instead?
> >
> > M-TAB switches desktop windows in many window managers.
> 
> Indeed.  I suggest using C-M-tab.

C-M-TAB is not available with some window managers.

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Philip K.]

Bastien <bzg@gnu.org> writes:

> Stefan Kangas <stefankangas@gmail.com> writes:
>
>> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>                                            ^^^^^^^
> Why not just <tab>, when point is on an outline entry?

I've tried something like this once, but it becomes quite annoying in
lisp modes, because "(" becomes a outline entry, making it tricky to
indent some code with TAB from anywhere on the line.

-- 
	Philip K.

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Bastien]

Eli Zaretskii <eliz@gnu.org> writes:

> C-M-TAB is not available with some window managers.

Yes, right.  Would C-S-TAB be a better candidate then?

-- 
 Bastien

bug#41130: outline-mode: Add new commands like org-cycle and org=global-cycle

[Bastien]

Hi Philip,

"Philip K." <philip@warpmail.net> writes:

> Bastien <bzg@gnu.org> writes:
>
>> Stefan Kangas <stefankangas@gmail.com> writes:
>>
>>> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>>                                            ^^^^^^^
>> Why not just <tab>, when point is on an outline entry?
>
> I've tried something like this once, but it becomes quite annoying in
> lisp modes, because "(" becomes a outline entry, making it tricky to
> indent some code with TAB from anywhere on the line.

Er, yes, you're right.  Then I'd suggest this:

    S-TAB for outline-cycle
  C-S-TAB for outline-global-cycle

IMO it is more common to want to cycle an entry than the whole buffer.

-- 
 Bastien

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Eli Zaretskii]

> From: Bastien <bzg@gnu.org>
> Cc: stefan@marxist.se,  41130@debbugs.gnu.org,  juri@linkov.net
> Date: Sun, 24 May 2020 18:26:50 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > C-M-TAB is not available with some window managers.
> 
> Yes, right.  Would C-S-TAB be a better candidate then?

Maybe.  It's free here.  I'll let people who know about its use to
chime in.

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Dmitry Gutov]

On 24.05.2020 19:39, Eli Zaretskii wrote:
>> Yes, right.  Would C-S-TAB be a better candidate then?
> Maybe.  It's free here.  I'll let people who know about its use to
> chime in.

C-S-TAB invoked tab-previous in tab-bar-mode. Like in many other programs.

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Bastien]

Dmitry Gutov <dgutov@yandex.ru> writes:

> On 24.05.2020 19:39, Eli Zaretskii wrote:
>>> Yes, right.  Would C-S-TAB be a better candidate then?
>> Maybe.  It's free here.  I'll let people who know about its use to
>> chime in.
>
> C-S-TAB invoked tab-previous in tab-bar-mode. Like in many other
> programs.

Yes, of course, you are right.  

I'm leaning toward binding C-c C-TAB for `org-force-cycle-archived'
which, again, I don't expect to be that much used by Org users.

-- 
 Bastien

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Basil L. Contovounesios]

Bastien <bzg@gnu.org> writes:

> Dmitry Gutov <dgutov@yandex.ru> writes:
>
>> On 24.05.2020 19:39, Eli Zaretskii wrote:
>>>> Yes, right.  Would C-S-TAB be a better candidate then?
>>> Maybe.  It's free here.  I'll let people who know about its use to
>>> chime in.
>>
>> C-S-TAB invoked tab-previous in tab-bar-mode. Like in many other
>> programs.
>
> Yes, of course, you are right.  
>
> I'm leaning toward binding C-c C-TAB for `org-force-cycle-archived'
> which, again, I don't expect to be that much used by Org users.

Isn't TAB often the same thing as C-i, at least in text terminals?  It
would be nice to have something that works in such environments as well,
unlike some exotic Org bindings.

-- 
Basil

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Howard Melman]

Has the previously mentioned patch been applied yet? I'm looking in master here and don't see it:
http://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/outline.el

I just upgraded to Emacs 27.1 and found that the new org-mode included no longer supports my hack of calling org-global-cycle from non-org-mode buffers which use outline-minor-mode.  As such I'm interested in getting this working and would love if it could be included in Emacs 27.2.

Howard

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Eli Zaretskii]

> From: Howard Melman <hmelman@gmail.com>
> Date: Mon, 17 Aug 2020 18:30:04 -0400
> 
> Has the previously mentioned patch been applied yet? I'm looking in master here and don't see it:
> http://git.savannah.gnu.org/cgit/emacs.git/tree/lisp/outline.el
> 
> I just upgraded to Emacs 27.1 and found that the new org-mode included no longer supports my hack of calling org-global-cycle from non-org-mode buffers which use outline-minor-mode.  As such I'm interested in getting this working and would love if it could be included in Emacs 27.2.

This is a new feature, so it's inappropriate for 27.2, which will be a
bug-fix release.  Sorry.

bug#41130: outline-mode: Add new commands like org-cycle and org-global-cycle

[Bastien]

Hi Basil,

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> Isn't TAB often the same thing as C-i, at least in text terminals?  It
> would be nice to have something that works in such environments as well,
> unlike some exotic Org bindings.

Yes, I agree.  Patch welcome!

-- 
 Bastien

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Lars Ingebrigtsen]

Yuan Fu <casouri@gmail.com> writes:

> Ah sorry, I switched to a new way to generate patches and didn’t
> notice that the commit message is gone. It is included this time.

Skimming this thread, it seemed that everybody was in agreement that
this was a good change, but the patch was never applied, so I did that
now.

Some discussion then followed about what key(s) would be the best ones
here, and I didn't see any consensus, so I left the patch as is.  Feel
free to change the keys as you want, but I'm closing this bug report.

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

bug#41198: bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

> On Oct 12, 2020, at 11:16 PM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
> Yuan Fu <casouri@gmail.com> writes:
> 
>> Ah sorry, I switched to a new way to generate patches and didn’t
>> notice that the commit message is gone. It is included this time.
> 
> Skimming this thread, it seemed that everybody was in agreement that
> this was a good change, but the patch was never applied, so I did that
> now.
> 
> Some discussion then followed about what key(s) would be the best ones
> here, and I didn't see any consensus, so I left the patch as is.  Feel
> free to change the keys as you want, but I'm closing this bug report.
> 
> -- 
> (domestic pets only, the antidote for overdose, milk.)
>   bloggy blog: http://lars.ingebrigtsen.no

Thanks Lars :-)

bug#41198: bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Juri Linkov]

> Skimming this thread, it seemed that everybody was in agreement that
> this was a good change, but the patch was never applied, so I did that
> now.

Now finally org keys are available in etc/NEWS, nice!
But typing S-TAB at the beginning of etc/NEWS signals the error:

  Debugger entered--Lisp error: (error "Before first heading")
    signal(error ("Before first heading"))

This is not how org-mode works - S-TAB doesn't fail before first heading
in org-mode.

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

>> Skimming this thread, it seemed that everybody was in agreement that
>> this was a good change, but the patch was never applied, so I did that
>> now.
>
> Now finally org keys are available in etc/NEWS, nice!
> But typing S-TAB at the beginning of etc/NEWS signals the error:
>
>   Debugger entered--Lisp error: (error "Before first heading")
>     signal(error ("Before first heading"))
>
> This is not how org-mode works - S-TAB doesn't fail before first heading
> in org-mode.

How does it work in org-mode?

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

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Robert Pluim]

>>>>> On Thu, 15 Oct 2020 09:02:25 +0200, Lars Ingebrigtsen <larsi@gnus.org> said:

    Lars> Juri Linkov <juri@linkov.net> writes:
    >>> Skimming this thread, it seemed that everybody was in agreement that
    >>> this was a good change, but the patch was never applied, so I did that
    >>> now.
    >> 
    >> Now finally org keys are available in etc/NEWS, nice!
    >> But typing S-TAB at the beginning of etc/NEWS signals the error:
    >> 
    >> Debugger entered--Lisp error: (error "Before first heading")
    >> signal(error ("Before first heading"))
    >> 
    >> This is not how org-mode works - S-TAB doesn't fail before first heading
    >> in org-mode.

    Lars> How does it work in org-mode?

The same as anywhere else: it cycles the visibility of the headings downbuffer.

Robert
-- 

bug#41198: bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

> On Oct 14, 2020, at 3:24 PM, Juri Linkov <juri@linkov.net> wrote:
> 
>> Skimming this thread, it seemed that everybody was in agreement that
>> this was a good change, but the patch was never applied, so I did that
>> now.
> 
> Now finally org keys are available in etc/NEWS, nice!
> But typing S-TAB at the beginning of etc/NEWS signals the error:
> 
>  Debugger entered--Lisp error: (error "Before first heading")
>    signal(error ("Before first heading"))
> 
> This is not how org-mode works - S-TAB doesn't fail before first heading
> in org-mode.

Do you suggest to change it to a user-error? Or just be silent?

Yuan

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

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



> On Oct 15, 2020, at 7:33 PM, Yuan Fu <casouri@gmail.com> wrote:
> 
> 
> 
>> On Oct 14, 2020, at 3:24 PM, Juri Linkov <juri@linkov.net> wrote:
>> 
>>> Skimming this thread, it seemed that everybody was in agreement that
>>> this was a good change, but the patch was never applied, so I did that
>>> now.
>> 
>> Now finally org keys are available in etc/NEWS, nice!
>> But typing S-TAB at the beginning of etc/NEWS signals the error:
>> 
>> Debugger entered--Lisp error: (error "Before first heading")
>>   signal(error ("Before first heading"))
>> 
>> This is not how org-mode works - S-TAB doesn't fail before first heading
>> in org-mode.
> 
> Do you suggest to change it to a user-error? Or just be silent?
> 

This patch should suppresses errors in both commands. Let me use it for a while and see if it works ok.

Yuan



[-- Attachment #2: outline-fix.patch --]
[-- Type: application/octet-stream, Size: 2528 bytes --]

From ef70c39d52a3aa53e95beb64f877da78daffb0f4 Mon Sep 17 00:00:00 2001
From: Yuan Fu <casouri@gmail.com>
Date: Thu, 15 Oct 2020 22:20:20 -0400
Subject: [PATCH] Suppress "Before first headings" error in outline-cycle

* lisp/outline.el (outline-cycle, outline-cycle-buffer): Suppress error.
---
 lisp/outline.el | 41 ++++++++++++++++++++++-------------------
 1 file changed, 22 insertions(+), 19 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index a4ce9afb44..5e22850292 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1167,19 +1167,22 @@ outline-cycle
 `Headings only' means show sub headings but not their bodies.
 `Show all' means show all subheadings and their bodies."
   (interactive)
-  (pcase (outline--cycle-state)
-    ('hide-all
-     (if (outline-has-subheading-p)
-         (progn (outline-show-children)
-                (message "Only headings"))
-       (outline-show-subtree)
-       (message "Show all")))
-    ('headings-only
-     (outline-show-subtree)
-     (message "Show all"))
-    ('show-all
-     (outline-hide-subtree)
-     (message "Hide all"))))
+  (condition-case nil
+      (pcase (outline--cycle-state)
+        ('hide-all
+         (if (outline-has-subheading-p)
+             (progn (outline-show-children)
+                    (message "Only headings"))
+           (outline-show-subtree)
+           (message "Show all")))
+        ('headings-only
+         (outline-show-subtree)
+         (message "Show all"))
+        ('show-all
+         (outline-hide-subtree)
+         (message "Hide all")))
+    ;; If error: "Before first heading" occurs, ignore it.
+    (error nil)))
 
 (defvar-local outline--cycle-buffer-state 'show-all
   "Internal variable used for tracking buffer cycle state.")
@@ -1190,12 +1193,12 @@ outline-cycle-buffer
   (pcase outline--cycle-buffer-state
     ('show-all
      (save-excursion
-       (let ((start-point (point)))
-         (while (not (eq (point) start-point))
-           (outline-up-heading 1))
-         (outline-hide-sublevels
-          (progn (outline-back-to-heading)
-                 (funcall 'outline-level)))))
+       (outline-hide-sublevels
+        ;; If error: "Before first heading" occurs, ignore it.
+        (or (ignore-errors
+              (outline-back-to-heading)
+              (outline-level))
+            1)))
      (setq outline--cycle-buffer-state 'top-level)
      (message "Top level headings"))
     ('top-level
-- 
2.27.0

bug#41198: bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Lars Ingebrigtsen]

Yuan Fu <casouri@gmail.com> writes:

> Do you suggest to change it to a user-error? Or just be silent?

Robert suggested:

>     Lars> How does it work in org-mode?
>
> The same as anywhere else: it cycles the visibility of the headings
> downbuffer.

I guess that makes sense?  I don't use outlining, though, so I don't
really know whether that would be surprising behaviour in outline mode,
though.

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

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Juri Linkov]

>> Now finally org keys are available in etc/NEWS, nice!
>> But typing S-TAB at the beginning of etc/NEWS signals the error:
>>
>>  Debugger entered--Lisp error: (error "Before first heading")
>>    signal(error ("Before first heading"))
>>
>> This is not how org-mode works - S-TAB doesn't fail before first heading
>> in org-mode.
>
> Do you suggest to change it to a user-error? Or just be silent?

To imitate org-mode, maybe outline-mode could temporarily (i.e. by
using save-excursion) navigate to the first heading before running
the rest of outline-cycle-buffer when it's before first heading?

Thank you for this nice feature!

bug#41130: bug#41198: bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Robert Pluim]

>>>>> On Fri, 16 Oct 2020 06:59:37 +0200, Lars Ingebrigtsen <larsi@gnus.org> said:

    Lars> Yuan Fu <casouri@gmail.com> writes:
    >> Do you suggest to change it to a user-error? Or just be silent?

    Lars> Robert suggested:

    Lars> How does it work in org-mode?
    >> 
    >> The same as anywhere else: it cycles the visibility of the headings
    >> downbuffer.

    Lars> I guess that makes sense?  I don't use outlining, though, so I don't
    Lars> really know whether that would be surprising behaviour in outline mode,
    Lars> though.

I donʼt think Iʼd find it surprising. Of course we could fix this by
just adding "* " to the first line of NEWS :-)

Robert
-- 

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

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



> On Oct 16, 2020, at 4:20 AM, Juri Linkov <juri@linkov.net> wrote:
> 
>>> Now finally org keys are available in etc/NEWS, nice!
>>> But typing S-TAB at the beginning of etc/NEWS signals the error:
>>> 
>>> Debugger entered--Lisp error: (error "Before first heading")
>>>   signal(error ("Before first heading"))
>>> 
>>> This is not how org-mode works - S-TAB doesn't fail before first heading
>>> in org-mode.
>> 
>> Do you suggest to change it to a user-error? Or just be silent?
> 
> To imitate org-mode, maybe outline-mode could temporarily (i.e. by
> using save-excursion) navigate to the first heading before running
> the rest of outline-cycle-buffer when it's before first heading?


This patch should make outline behaves like org: S-TAB always cycle the whole buffer, regardless where is the point. TAB cycles a heading, and does nothing if point is before the first heading.

Yuan


[-- Attachment #2: outline-fix.patch --]
[-- Type: application/octet-stream, Size: 2400 bytes --]

From 147b547355380d134f423b44c988ff18074a4ded Mon Sep 17 00:00:00 2001
From: Yuan Fu <casouri@gmail.com>
Date: Thu, 15 Oct 2020 22:20:20 -0400
Subject: [PATCH] Suppress "Before first headings" error in outline-cycle

* lisp/outline.el (outline-cycle): Suppress error.
(outline-cycle-buffer): Simply pass 1 to 'outline-hide-sublevels'.
---
 lisp/outline.el | 37 +++++++++++++++++--------------------
 1 file changed, 17 insertions(+), 20 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index a4ce9afb44..05c884fb95 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1167,19 +1167,22 @@ outline-cycle
 `Headings only' means show sub headings but not their bodies.
 `Show all' means show all subheadings and their bodies."
   (interactive)
-  (pcase (outline--cycle-state)
-    ('hide-all
-     (if (outline-has-subheading-p)
-         (progn (outline-show-children)
-                (message "Only headings"))
-       (outline-show-subtree)
-       (message "Show all")))
-    ('headings-only
-     (outline-show-subtree)
-     (message "Show all"))
-    ('show-all
-     (outline-hide-subtree)
-     (message "Hide all"))))
+  (condition-case nil
+      (pcase (outline--cycle-state)
+        ('hide-all
+         (if (outline-has-subheading-p)
+             (progn (outline-show-children)
+                    (message "Only headings"))
+           (outline-show-subtree)
+           (message "Show all")))
+        ('headings-only
+         (outline-show-subtree)
+         (message "Show all"))
+        ('show-all
+         (outline-hide-subtree)
+         (message "Hide all")))
+    ;; If error: "Before first heading" occurs, ignore it.
+    (error nil)))
 
 (defvar-local outline--cycle-buffer-state 'show-all
   "Internal variable used for tracking buffer cycle state.")
@@ -1189,13 +1192,7 @@ outline-cycle-buffer
   (interactive)
   (pcase outline--cycle-buffer-state
     ('show-all
-     (save-excursion
-       (let ((start-point (point)))
-         (while (not (eq (point) start-point))
-           (outline-up-heading 1))
-         (outline-hide-sublevels
-          (progn (outline-back-to-heading)
-                 (funcall 'outline-level)))))
+     (outline-hide-sublevels 1)
      (setq outline--cycle-buffer-state 'top-level)
      (message "Top level headings"))
     ('top-level
-- 
2.27.0

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Lars Ingebrigtsen]

Yuan Fu <casouri@gmail.com> writes:

> This patch should make outline behaves like org: S-TAB always cycle
> the whole buffer, regardless where is the point. TAB cycles a heading,
> and does nothing if point is before the first heading.

I think the behaviour makes sense, but the implementation isn't ideal:

[...]

> +  (condition-case nil
> +      (pcase (outline--cycle-state)
> +        ('hide-all
> +         (if (outline-has-subheading-p)
> +             (progn (outline-show-children)
> +                    (message "Only headings"))
> +           (outline-show-subtree)
> +           (message "Show all")))
> +        ('headings-only
> +         (outline-show-subtree)
> +         (message "Show all"))
> +        ('show-all
> +         (outline-hide-subtree)
> +         (message "Hide all")))
> +    ;; If error: "Before first heading" occurs, ignore it.
> +    (error nil)))

This is basically an `ignore-errors' around a whole bunch of code, used
as a program flow mechanism, and that's always awkward, because it hides
real errors in the code.

Altering the functions to not error out in these situations would be
better.

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

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Juri Linkov]

>> +  (condition-case nil
>> +      (pcase (outline--cycle-state)
>> +        ('hide-all
>> +         (if (outline-has-subheading-p)
>> +             (progn (outline-show-children)
>> +                    (message "Only headings"))
>> +           (outline-show-subtree)
>> +           (message "Show all")))
>> +        ('headings-only
>> +         (outline-show-subtree)
>> +         (message "Show all"))
>> +        ('show-all
>> +         (outline-hide-subtree)
>> +         (message "Hide all")))
>> +    ;; If error: "Before first heading" occurs, ignore it.
>> +    (error nil)))
>
> This is basically an `ignore-errors' around a whole bunch of code, used
> as a program flow mechanism, and that's always awkward, because it hides
> real errors in the code.
>
> Altering the functions to not error out in these situations would be
> better.

Like 'outline-back-to-heading' has an optional argument 'invisible-ok',
maybe a new argument named 'error-ok' or 'outside-ok' could
be added to not error out when point is outside of the outline tree.

bug#41198: bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

> On Oct 17, 2020, at 4:30 PM, Juri Linkov <juri@linkov.net> wrote:
> 
>>> +  (condition-case nil
>>> +      (pcase (outline--cycle-state)
>>> +        ('hide-all
>>> +         (if (outline-has-subheading-p)
>>> +             (progn (outline-show-children)
>>> +                    (message "Only headings"))
>>> +           (outline-show-subtree)
>>> +           (message "Show all")))
>>> +        ('headings-only
>>> +         (outline-show-subtree)
>>> +         (message "Show all"))
>>> +        ('show-all
>>> +         (outline-hide-subtree)
>>> +         (message "Hide all")))
>>> +    ;; If error: "Before first heading" occurs, ignore it.
>>> +    (error nil)))
>> 
>> This is basically an `ignore-errors' around a whole bunch of code, used
>> as a program flow mechanism, and that's always awkward, because it hides
>> real errors in the code.
>> 
>> Altering the functions to not error out in these situations would be
>> better.
> 
> Like 'outline-back-to-heading' has an optional argument 'invisible-ok',
> maybe a new argument named 'error-ok' or 'outside-ok' could
> be added to not error out when point is outside of the outline tree.

I can modify outline code to signal a signal (say ‘outline-before-first-heading) rather than an error, and handle that signal specifically. How’s that?

Yuan

bug#41198: bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Lars Ingebrigtsen]

Yuan Fu <casouri@gmail.com> writes:

> I can modify outline code to signal a signal (say
> ‘outline-before-first-heading) rather than an error, and handle that
> signal specifically. How’s that?

Yes, that would also work.

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

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Yuan Fu]

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



> On Oct 18, 2020, at 4:36 AM, Lars Ingebrigtsen <larsi@gnus.org> wrote:
> 
> Yuan Fu <casouri@gmail.com> writes:
> 
>> I can modify outline code to signal a signal (say
>> ‘outline-before-first-heading) rather than an error, and handle that
>> signal specifically. How’s that?
> 
> Yes, that would also work.
> 
> -- 
> (domestic pets only, the antidote for overdose, milk.)
>   bloggy blog: http://lars.ingebrigtsen.no

Here is the new patch.

Yuan


[-- Attachment #2: outline-fix.patch --]
[-- Type: application/octet-stream, Size: 3274 bytes --]

From ff4722534c1e47a2536257116436b66c79db3e8b Mon Sep 17 00:00:00 2001
From: Yuan Fu <casouri@gmail.com>
Date: Thu, 15 Oct 2020 22:20:20 -0400
Subject: [PATCH] Handle "Before first headings" error in outline-cycle

* lisp/outline.el (outline-before-first-heading): New error.
(outline-back-to-heading): Signal the new error.
(outline-cycle): Ignore the error.
(outline-cycle-buffer): Simply pass 1 to 'outline-hide-sublevels'.
---
 lisp/outline.el | 40 +++++++++++++++++++---------------------
 1 file changed, 19 insertions(+), 21 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index a4ce9afb44..b9806bc187 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -402,6 +402,8 @@ outline-invisible-p
 If POS is nil, use `point' instead."
   (eq (get-char-property (or pos (point)) 'invisible) 'outline))
 
+(define-error 'outline-before-first-heading "Before first heading")
+
 (defun outline-back-to-heading (&optional invisible-ok)
   "Move to previous heading line, or beg of this line if it's a heading.
 Only visible heading lines are considered, unless INVISIBLE-OK is non-nil."
@@ -412,7 +414,7 @@ outline-back-to-heading
 	  (while (not found)
 	    (or (re-search-backward (concat "^\\(?:" outline-regexp "\\)")
 				    nil t)
-                (error "Before first heading"))
+                (signal 'outline-before-first-heading nil))
 	    (setq found (and (or invisible-ok (not (outline-invisible-p)))
 			     (point)))))
 	(goto-char found)
@@ -1167,19 +1169,21 @@ outline-cycle
 `Headings only' means show sub headings but not their bodies.
 `Show all' means show all subheadings and their bodies."
   (interactive)
-  (pcase (outline--cycle-state)
-    ('hide-all
-     (if (outline-has-subheading-p)
-         (progn (outline-show-children)
-                (message "Only headings"))
-       (outline-show-subtree)
-       (message "Show all")))
-    ('headings-only
-     (outline-show-subtree)
-     (message "Show all"))
-    ('show-all
-     (outline-hide-subtree)
-     (message "Hide all"))))
+  (condition-case nil
+      (pcase (outline--cycle-state)
+        ('hide-all
+         (if (outline-has-subheading-p)
+             (progn (outline-show-children)
+                    (message "Only headings"))
+           (outline-show-subtree)
+           (message "Show all")))
+        ('headings-only
+         (outline-show-subtree)
+         (message "Show all"))
+        ('show-all
+         (outline-hide-subtree)
+         (message "Hide all")))
+    (outline-before-first-heading nil)))
 
 (defvar-local outline--cycle-buffer-state 'show-all
   "Internal variable used for tracking buffer cycle state.")
@@ -1189,13 +1193,7 @@ outline-cycle-buffer
   (interactive)
   (pcase outline--cycle-buffer-state
     ('show-all
-     (save-excursion
-       (let ((start-point (point)))
-         (while (not (eq (point) start-point))
-           (outline-up-heading 1))
-         (outline-hide-sublevels
-          (progn (outline-back-to-heading)
-                 (funcall 'outline-level)))))
+     (outline-hide-sublevels 1)
      (setq outline--cycle-buffer-state 'top-level)
      (message "Top level headings"))
     ('top-level
-- 
2.27.0

bug#41130: bug#41198: 27.0.60; [PATCH] heading cycling command for outline

[Lars Ingebrigtsen]

Yuan Fu <casouri@gmail.com> writes:

> Here is the new patch.

Thanks; looks good to me.  I've now pushed it to the trunk.

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

bug#41198: 28.0.50; heading cycling command for outline

[Paul W. Rankin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Hello,

Sorry to revisit this but there are a few edge cases with the new 
outline-cycle and outline-cycle-buffer commands...


1. In command outline-hide-sublevels#L901 we see:

       ;; Finally unhide any trailing newline.
       (goto-char (point-max))
       (if (and (bolp) (not (bobp)) (outline-invisible-p (1- (point))))
           (outline-flag-region (1- (point)) (point) nil))))

When calling this function the overlay created to hide the buffer's 
final subheading ends at the end-of-subtree - 1. This means that the 
following code in outline--cycle-state#L1130 fails with an off-by-1:

             ((and (eq (overlay-end (car ov-list)) end)
                   (eq (overlay-start (car ov-list)) heading-end))

The result of this is that when calling outline-cycle-buffer to set the 
outline in a top-level state, if the user navigates to the last 
top-level heading and presses TAB for outline-cycle, the expectation is 
to show that heading's subheadings, but the result is show all.

To fix, if leaving outline-hide-sublevels alone, a workaround would be:

diff --git a/lisp/outline.el b/lisp/outline.el
index 47e6528859..054d2cb62b 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1127,7 +1127,7 @@ outline--cycle-state
        (cond ((eq ov-list nil) 'show-all)
              ;; (eq (length ov-list) 1) wouldn’t work: what if there is
              ;; one folded subheading?
-            ((and (eq (overlay-end (car ov-list)) end)
+            ((and (<= 0 (- end (overlay-end (car ov-list))) 1)
                    (eq (overlay-start (car ov-list)) heading-end))
               'hide-all)
              (t 'headings-only)))))


2. This may sound strange, but overlays with an invisible property of 
'outline are not guaranteed to be overlays for collapsed outline 
headings. This is true if a lisp program has used outline-flag-region 
for something other than an outline heading. I had done this for 
collapsing a major mode's notes markup:

     [[ here's a note ]] -> [[...]]

This is simply solved by testing each overlay-start with 
outline-on-heading-p:

diff --git a/lisp/outline.el b/lisp/outline.el
index 054d2cb62b..a05cf87d4e 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1121,10 +1121,15 @@ outline--cycle-state
        (setq heading-end (point))
        (outline-end-of-subtree)
        (setq end (point))
-      (setq ov-list (cl-remove-if-not
-                     (lambda (o) (eq (overlay-get o 'invisible) 
'outline))
-                     (overlays-in start end)))
-      (cond ((eq ov-list nil) 'show-all)
+      (setq ov-list
+            (seq-filter
+             (lambda (o)
+               (and (eq (overlay-get o 'invisible) 'outline)
+                    (save-excursion
+                      (goto-char (overlay-start o))
+                      (outline-on-heading-p t)))))
+            (overlays-in start end)))
+    (cond ((eq ov-list nil) 'show-all)
              ;; (eq (length ov-list) 1) wouldn’t work: what if there is
              ;; one folded subheading?
              ((and (<= 0 (- end (overlay-end (car ov-list))) 1)

n.b. This will fail if the user/program has changed 
outline-heading-end-regexp to have multiple newlines, because 
outline-on-heading-p only checks if it's looking at outline-regexp from 
the beginning of that line.


3. When a buffer contains outline headings of only < 1 (e.g. all 
headings are level 3) calling outline-cycle-buffer to show only 
top-level headings will results in an unexpected buffer state of:

     ...

This is fixed with a simple test of whether the buffer has top-level 
headings before allowing cycling to top-level.


-- 
Paul W. Rankin
https://www.paulwrankin.com

The single best thing you can do for the world is delete your social 
media accounts.

bug#41198: 28.0.50; heading cycling command for outline

[Lars Ingebrigtsen]

"Paul W. Rankin" via "Bug reports for GNU Emacs, the Swiss army knife of
text editors" <bug-gnu-emacs@gnu.org> writes:

> Sorry to revisit this but there are a few edge cases with the new 
> outline-cycle and outline-cycle-buffer commands...

The patches look OK to me, but look like they've been slightly mangled
during transmission, so could you include them as a single patch as an
attachment?  (And adding a ChangeLog-format text would also be nice.)

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

bug#41198: 28.0.50; heading cycling command for outline

[Paul W. Rankin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

On 2020-11-17 07:59, Lars Ingebrigtsen wrote:
> 
> The patches look OK to me, but look like they've been slightly mangled
> during transmission, so could you include them as a single patch as an
> attachment?  (And adding a ChangeLog-format text would also be nice.)

2x patches attached with changelog.

I took a more precise approach with outline--cycle-state, where the +1 
case is only handled when the subtree end is point-max, otherwise the 
overlay-end must equal end of subtree point in all other cases.

I rewrote outline-cycle-buffer; it now first checks that the buffer has 
top-level headings before attempting to show only top-level headings, 
thus avoiding the disconcerting state where all buffer content is 
reduced to "...". If buffer has no outline headings, we still get an 
annoying message toggle from "All headings" to "Show all".

Also this avoids using pcase, which is awful.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-outline.el-better-handing-of-outline-overlays-w.patch --]
[-- Type: text/x-diff; name=0001-lisp-outline.el-better-handing-of-outline-overlays-w.patch, Size: 1902 bytes --]

From c589e4055aad93aceefe0ebb3281c008c82a0b46 Mon Sep 17 00:00:00 2001
From: "Paul W. Rankin" <pwr@skeletons.cc>
Date: Tue, 17 Nov 2020 12:42:47 +1000
Subject: [PATCH 1/2] * lisp/outline.el: better handing of outline overlays
 when cycling

(outline--cycle-state): only consider outline overlays that are on
  outline headings; when subtree end is point-max, return overlay-end +1
  because final subtree overlay only reaches point-max -1.
---
 lisp/outline.el | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index 47e6528859..8cc8a3cd89 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1121,14 +1121,19 @@ outline--cycle-state
       (setq heading-end (point))
       (outline-end-of-subtree)
       (setq end (point))
-      (setq ov-list (cl-remove-if-not
-                     (lambda (o) (eq (overlay-get o 'invisible) 'outline))
-                     (overlays-in start end)))
-      (cond ((eq ov-list nil) 'show-all)
-            ;; (eq (length ov-list) 1) wouldn’t work: what if there is
-            ;; one folded subheading?
-            ((and (eq (overlay-end (car ov-list)) end)
-                  (eq (overlay-start (car ov-list)) heading-end))
+      (setq ov-list
+            (seq-filter
+             (lambda (o)
+               (and (eq (overlay-get o 'invisible) 'outline)
+                    (save-excursion
+                      (goto-char (overlay-start o))
+                      (outline-on-heading-p t))))
+             (overlays-in start end)))
+      (cond ((null ov-list) 'show-all)
+            ((and (or (= end (point-max)
+                         (1+ (overlay-end (car ov-list))))
+                      (= (overlay-end (car ov-list)) end))
+                  (= (overlay-start (car ov-list)) heading-end))
              'hide-all)
             (t 'headings-only)))))
 
-- 
2.29.2


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-lisp-outline.el-avoid-hiding-all-buffer-content.patch --]
[-- Type: text/x-diff; name=0002-lisp-outline.el-avoid-hiding-all-buffer-content.patch, Size: 2252 bytes --]

From 680210c64545389502e7a2d05ec0c98e7b25c24b Mon Sep 17 00:00:00 2001
From: "Paul W. Rankin" <pwr@skeletons.cc>
Date: Tue, 17 Nov 2020 12:44:44 +1000
Subject: [PATCH 2/2] * lisp/outline.el: avoid hiding all buffer content

(outline-cycle-buffer): check that buffer has top-level headings
  before calling outline-hide-sublevels 1 thus preventing disconcerting
  buffer state of content reduced to single "..."
---
 lisp/outline.el | 38 ++++++++++++++++++++++++--------------
 1 file changed, 24 insertions(+), 14 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index 8cc8a3cd89..9b11b86b9d 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1173,20 +1173,30 @@ outline--cycle-buffer-state
 (defun outline-cycle-buffer ()
   "Cycle the whole buffer like in `outline-cycle'."
   (interactive)
-  (pcase outline--cycle-buffer-state
-    ('show-all
-     (outline-hide-sublevels 1)
-     (setq outline--cycle-buffer-state 'top-level)
-     (message "Top level headings"))
-    ('top-level
-     (outline-show-all)
-     (outline-hide-region-body (point-min) (point-max))
-     (setq outline--cycle-buffer-state 'all-heading)
-     (message "All headings"))
-    ('all-heading
-     (outline-show-all)
-     (setq outline--cycle-buffer-state 'show-all)
-     (message "Show all"))))
+  (let (has-top-level)
+    (save-excursion
+      (goto-char (point-min))
+      (while (not (or has-top-level (eobp)))
+        (when (outline-on-heading-p t)
+          (when (= (funcall outline-level) 1)
+            (setq has-top-level t)))
+        (outline-next-heading)))
+    (cond
+     ((and (eq outline--cycle-buffer-state 'show-all)
+           has-top-level)
+      (outline-hide-sublevels 1)
+      (setq outline--cycle-buffer-state 'top-level)
+      (message "Top level headings"))
+     ((or (eq outline--cycle-buffer-state 'show-all)
+          (eq outline--cycle-buffer-state 'top-level))
+      (outline-show-all)
+      (outline-hide-region-body (point-min) (point-max))
+      (setq outline--cycle-buffer-state 'all-heading)
+      (message "All headings"))
+     (t
+      (outline-show-all)
+      (setq outline--cycle-buffer-state 'show-all)
+      (message "Show all")))))
 
 (provide 'outline)
 (provide 'noutline)
-- 
2.29.2

bug#41198: 28.0.50; heading cycling command for outline

[Lars Ingebrigtsen]

"Paul W. Rankin" <pwr@skeletons.cc> writes:

> 2x patches attached with changelog.

Thanks; looks OK to me, so I've applied it to Emacs 28.

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

bug#41198: 28.0.50; heading cycling command for outline

[Juri Linkov]

>> 2x patches attached with changelog.
>
> Thanks; looks OK to me, so I've applied it to Emacs 28.

BTW, since now S-TAB cycles headings nicely in etc/NEWS,
what about enabling outline-minor-mode in the output
Help buffer of 'C-h b'?  Currently its section
"Key translations" is so long that it takes too much time
to scroll down to the most interesting section
"Major Mode Bindings".  With outline-minor-mode it would
be possible to collapse "Key translations" initially.
Then typing S-TAB would show such nice overview:

* Key translations
* `override-global-mode' Minor Mode Bindings
* `outline-minor-mode' Minor Mode Bindings
* recentf-mode Minor Mode Bindings
* Major Mode Bindings
* Global Bindings
* Function key map translations
* Input decoding map translations

bug#41198: 28.0.50; heading cycling command for outline

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> BTW, since now S-TAB cycles headings nicely in etc/NEWS,
> what about enabling outline-minor-mode in the output
> Help buffer of 'C-h b'?  Currently its section
> "Key translations" is so long that it takes too much time
> to scroll down to the most interesting section
> "Major Mode Bindings".

Yes, that's a general problem, I think -- I'm often tapping `C-h b' to
look for something, but then getting a wall of stuff that's never what
I'm interested in (i.e., the "Key translation" stuff), and no easy way
to navigate to the sections that I'm looking far.

> With outline-minor-mode it would
> be possible to collapse "Key translations" initially.
> Then typing S-TAB would show such nice overview:
>
> * Key translations
> * `override-global-mode' Minor Mode Bindings
> * `outline-minor-mode' Minor Mode Bindings
> * recentf-mode Minor Mode Bindings
> * Major Mode Bindings
> * Global Bindings
> * Function key map translations
> * Input decoding map translations

I think this is a good idea.

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

bug#41198: 28.0.50; heading cycling command for outline

[Juri Linkov]

>> With outline-minor-mode it would
>> be possible to collapse "Key translations" initially.
>> Then typing S-TAB would show such nice overview:
>>
>> * Key translations
>> * `override-global-mode' Minor Mode Bindings
>> * `outline-minor-mode' Minor Mode Bindings
>> * recentf-mode Minor Mode Bindings
>> * Major Mode Bindings
>> * Global Bindings
>> * Function key map translations
>> * Input decoding map translations
>
> I think this is a good idea.

I tried to modify the format of `C-h b' to output '*' headings,
but unfortunately after enabling `outline-minor-mode'
TAB has no effect on such headings.

I wonder why heading cycling implemented in this bug report
supports only `outline-mode', but not `outline-minor-mode'?

It would make sense in `outline-minor-mode' if TAB typed on a heading
then cycle outline heading.  If TAB is typed outside of a heading,
then use the default TAB binding, e.g. in case of the Help buffer
navigate to the next link.

bug#41198: 28.0.50; heading cycling command for outline

[Drew Adams]

> I wonder why heading cycling implemented in this bug report
> supports only `outline-mode', but not `outline-minor-mode'?

`outline-minor-mode' is a thousand times more
useful than `outline-mode', IMO.

There should probably be few cases where no
other major mode makes sense, and we really
want to use `outline-mode'.  (Just a guess.)

bug#41198: 28.0.50; heading cycling command for outline

[Paul W. Rankin via Bug reports for GNU Emacs, the Swiss army knife of text editors]

On 2020-11-27 18:29, Juri Linkov wrote:
> I tried to modify the format of `C-h b' to output '*' headings,
> but unfortunately after enabling `outline-minor-mode'
> TAB has no effect on such headings.
> 
> I wonder why heading cycling implemented in this bug report
> supports only `outline-mode', but not `outline-minor-mode'?
> 
> It would make sense in `outline-minor-mode' if TAB typed on a heading
> then cycle outline heading.  If TAB is typed outside of a heading,
> then use the default TAB binding, e.g. in case of the Help buffer
> navigate to the next link.

This is because it's not possible to know how the underlying major mode 
implements TAB.

For just one example, I maintain a major mode where TAB performs outline 
cycling when at a heading, but calls completion-at-point when at a 
heading but at eolp. The assumption of outline-on-heading-p is 
insufficient to allow outline-minor-mode to hijack TAB.

The correct way to implement what you're suggesting is for the major 
mode to require outline as a library, then alias the cycling commands 
prefixed as MODE-outline-cycle[-buffer] mapped them to TAB/S-TAB in 
their own keymaps.

bug#41198: 28.0.50; heading cycling command for outline

[Howard Melman]

"Paul W. Rankin" via "Bug reports for GNU Emacs, the Swiss
army knife of text editors" <bug-gnu-emacs@gnu.org> writes:

> On 2020-11-27 18:29, Juri Linkov wrote:
>> I wonder why heading cycling implemented in this bug
>> report supports only `outline-mode', but not
>> `outline-minor-mode'?  It would make sense in
>> `outline-minor-mode' if TAB typed on a heading then cycle
>> outline heading.  If TAB is typed outside of a heading,
>> then use the default TAB binding, e.g. in case of the
>> Help buffer navigate to the next link.
>
> This is because it's not possible to know how the underlying major
> mode implements TAB.
>
> For just one example, I maintain a major mode where TAB performs
> outline cycling when at a heading, but calls completion-at-point when
> at a heading but at eolp. The assumption of outline-on-heading-p is 
> insufficient to allow outline-minor-mode to hijack TAB.
>
> The correct way to implement what you're suggesting is for the major
> mode to require outline as a library, then alias the cycling commands 
> prefixed as MODE-outline-cycle[-buffer] mapped them to TAB/S-TAB in
> their own keymaps.

I don't follow master so I'm not quite sure what's
implemented, but my original suggestion for this was:

(define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
(define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)

It's definitely very useful in outline-minor-mode. I use
this for code folding in prog-modes amongst other things and
that's one of the reasons I used C-TAB for outline-cycle
(since TAB often has other uses in prog-modes).

AFAIR people commented that C-TAB wasn't always available in
some terminals and said it should just be on TAB.  Fine.
Either way S-TAB should work.

I'd argue that if you're enabling outline-minor-mode in a
major mode that has a binding for TAB, you want it to be
overridden.  If not, don't enable the minor mode or change
one keymap to not conflict.  Maybe outline-minor-mode should
support a variable option a major mode could set to change
the TAB keybinding or at least not override it with a
minor-mode binding?

-- 

Howard

bug#41198: 28.0.50; heading cycling command for outline

[Juri Linkov]

> I don't follow master so I'm not quite sure what's
> implemented, but my original suggestion for this was:
>
> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>
> It's definitely very useful in outline-minor-mode. I use
> this for code folding in prog-modes amongst other things and
> that's one of the reasons I used C-TAB for outline-cycle
> (since TAB often has other uses in prog-modes).
>
> AFAIR people commented that C-TAB wasn't always available in
> some terminals and said it should just be on TAB.  Fine.
> Either way S-TAB should work.
>
> I'd argue that if you're enabling outline-minor-mode in a
> major mode that has a binding for TAB, you want it to be
> overridden.  If not, don't enable the minor mode or change
> one keymap to not conflict.  Maybe outline-minor-mode should
> support a variable option a major mode could set to change
> the TAB keybinding or at least not override it with a
> minor-mode binding?

This feature request was closed, so in a new feature request
in https://debbugs.gnu.org/45147#8 this is implemented as a new variable
'outline-minor-mode-cycle' that you can set to t to allow cycling keys
in 'outline-minor-mode', and a keymap 'outline-mode-cycle-map' where you
can define your bindings such as C-TAB instead of the default key TAB.

bug#41198: 28.0.50; heading cycling command for outline

[Juri Linkov]

> I don't follow master so I'm not quite sure what's
> implemented, but my original suggestion for this was:
>
> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)

This is what's implemented in master:

(define-key outline-minor-mode-map (kbd "<C-tab>") 'outline-cycle)
(define-key outline-minor-mode-map (kbd "<backtab>") 'outline-cycle-buffer)

bug#41198: 28.0.50; heading cycling command for outline

[Howard Melman]

Juri Linkov <juri@linkov.net> writes:

>> I don't follow master so I'm not quite sure what's
>> implemented, but my original suggestion for this was:
>>
>> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>
> This is what's implemented in master:
>
> (define-key outline-minor-mode-map (kbd "<C-tab>") 'outline-cycle)
> (define-key outline-minor-mode-map (kbd "<backtab>") 'outline-cycle-buffer)

Sounds great.  I look forward to Emacs 28.

-- 

Howard

bug#41198: 28.0.50; heading cycling command for outline

[Pankaj Jangid]

Juri Linkov <juri@linkov.net> writes:

>> I don't follow master so I'm not quite sure what's
>> implemented, but my original suggestion for this was:
>>
>> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>
> This is what's implemented in master:
>
> (define-key outline-minor-mode-map (kbd "<C-tab>") 'outline-cycle)
> (define-key outline-minor-mode-map (kbd "<backtab>") 'outline-cycle-buffer)

1. <tab> and <C-tab> have same binding on master i.e. both invoking
‘outline-cycle’.

2. Body of last heading doesn’t hide when using the above command.

bug#41198: 28.0.50; heading cycling command for outline

[Juri Linkov]

>>> I don't follow master so I'm not quite sure what's
>>> implemented, but my original suggestion for this was:
>>>
>>> (define-key outline-minor-mode-map (kbd "C-<tab>") 'outline-cycle)
>>> (define-key outline-minor-mode-map (kbd "S-<tab>") 'outline-global-cycle)
>>
>> This is what's implemented in master:
>>
>> (define-key outline-minor-mode-map (kbd "<C-tab>") 'outline-cycle)
>> (define-key outline-minor-mode-map (kbd "<backtab>") 'outline-cycle-buffer)
>
> 1. <tab> and <C-tab> have same binding on master i.e. both invoking
> ‘outline-cycle’.

I meant that with current master it's possible to add these bindings
in the init file because C-TAB and S-TAB they can't be bound by default
in outline-minor-mode to not interfere with major mode key bindings.

In outline-mode (not minor) in current master, TAB is bound to outline-cycle,
and S-TAB is bound to outline-cycle-buffer, but C-TAB is unbound in outline-mode
to not interfere with other uses of C-TAB.

> 2. Body of last heading doesn’t hide when using the above command.

This sounds like a bug.  Please provide a recipe for reproducing it.

bug#41198: 28.0.50; heading cycling command for outline

[Pankaj Jangid]

Juri Linkov <juri@linkov.net> writes:

>> 2. Body of last heading doesn’t hide when using the above command.
>
> This sounds like a bug.  Please provide a recipe for reproducing it.

Sorry. This was my fault. Somehow I was expecting all headings to
collapse with TAB key. TAB and S-TAB are perfectly working.

Not related. At present, I am on a text base virtual terminal on
Debian. And S-TAB is invoking C-M-i which triggers
ispell-complete-word. Is this a bug? To test the above thing,I had to
startx.

bug#41198: 28.0.50; heading cycling command for outline

[Juri Linkov]

> Not related. At present, I am on a text base virtual terminal on
> Debian. And S-TAB is invoking C-M-i which triggers
> ispell-complete-word. Is this a bug? To test the above thing,I had to
> startx.

Doesn't look like a bug.  S-TAB is unavailable on some terminals.

bug#41198: 28.0.50; heading cycling command for outline

[Pankaj Jangid]

Juri Linkov <juri@linkov.net> writes:

>> Not related. At present, I am on a text base virtual terminal on
>> Debian. And S-TAB is invoking C-M-i which triggers
>> ispell-complete-word. Is this a bug? To test the above thing,I had to
>> startx.
>
> Doesn't look like a bug.  S-TAB is unavailable on some terminals.

I guess, I was not clear enough. By text based virtual terminal I meant
when X is not running. The default text console of debian.