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

[Yuan Fu <casouri@gmail.com>]

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