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

[Yuan Fu <casouri@gmail.com>]

[-- 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 --]