Re: master 2ef6f943abd: Add option to control default outlining in 'C-h b'

[Robert Pluim <rpluim@gmail.com>]

>>>>> On Tue, 25 Apr 2023 20:32:23 +0200, Michael Heerdegen <michael_heerdegen@web.de> said:

    Michael> Eli Zaretskii <eliz@gnu.org> writes:
    >> What is the purpose of requesting a custom function to actually
    >> hide/unhide the headings, i.e. to know enough about the structure and
    >> internal details of Outline mode to do its job?

    Michael> I guess the idea is to let the user decide _how_ to unhide a sublevel:
    Michael> reveal only one level, N levels, everything, only a certain leaf and
    Michael> its parents, etc.  That's a useful feature.

    Michael> A nice semantics for the custom-function, although not backward
    Michael> compatible, that would still allow doing this, could be: if the non-nil
    Michael> return value of the custom-function is functionp, we call it.  Other
    Michael> non-nil values mean we perform some default action, like showing the
    Michael> complete subbranch.

Or we could have a 100% backwards compatible implementation like this,
which Iʼd push to emacs-29 if it wasnʼt in pre-release :-)

From a7883d52f808568816e3f144fadbeacdd6f2cdfe Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim@gmail.com>
Date: Tue, 25 Apr 2023 12:21:36 +0200
Subject: [PATCH] Make outline-default-rules custom-function a predicate
To: emacs-devel@gnu.org

* lisp/outline.el (outline--show-headings-up-to-level): Add
`predicate' as an option: hide the entry if it returns non-nil.
(outline-default-rules): Adjust docstring to behavior change.
---
 lisp/outline.el | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index 97a51c9b92a..c5631cf12e2 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1519,10 +1519,11 @@ outline-default-rules
 
 When nil, the subtree is hidden unconditionally.
 
-When equal to a list, each element should be one of the following:
+When equal to a list, each element should be one of the
+following, which are checked in order:
 
 - A cons cell with CAR `match-regexp' and CDR a regexp, the
-  subtree will be hidden when the outline heading match the
+  subtree will be hidden when the outline heading matches the
   regexp.
 
 - `subtree-has-long-lines' to only show the heading branches when
@@ -1532,11 +1533,17 @@ outline-default-rules
 - `subtree-is-long' to only show the heading branches when its
   subtree contains more than `outline-default-line-count' lines.
 
-- A cons cell of the form (custom-function . FUNCTION) where
+- A cons cell of the form (predicate . FUNCTION) where
   FUNCTION is a lambda function or function name which will be
-  called without arguments with point at the beginning of the
-  heading and the match data set appropriately, the function
-  being expected to toggle the heading visibility."
+  called without arguments, with point at the beginning of the
+  heading, and the match data set appropriately.  If the function
+  returns nil the subtree will be shown, otherwise it is hidden.
+
+- A cons cell of the form (custom-function . FUNCTION).  This is
+  similar to the `predicate' form, in that the FUNCTION will be
+  called, but its return value is ignored.  The function is
+  expected to set the visibility of the subtree directly using
+  `outline-hide-entry', `outline-show-branches' etc."
   :version "29.1"
   :type '(choice (const :tag "Hide subtree" nil)
                  (set :tag "Show subtree unless"
@@ -1546,6 +1553,8 @@ outline-default-rules
                              subtree-has-long-lines)
                       (const :tag "Subtree is long"
                              subtree-is-long)
+                      (cons :tag "Predicate"
+                            (const predicate) function)
                       (cons :tag "Custom function"
                             (const custom-function) function))))
 
@@ -1608,6 +1617,9 @@ outline--show-headings-up-to-level
               (memq 'subtree-is-long outline-default-rules))
              (check-long-lines
               (memq 'subtree-has-long-lines outline-default-rules))
+             (predicate
+              (cdr-safe
+               (assoc 'predicate outline-default-rules)))
              (custom-function
               (cdr-safe
                (assoc 'custom-function outline-default-rules))))
@@ -1651,6 +1663,10 @@ outline--show-headings-up-to-level
                  ;; show only branches when long lines are detected
                  ;; in subtree
                  (outline-show-branches))
+                (predicate
+                 (if (funcall predicate)
+                     (outline-hide-entry)
+                   (outline-show-subtree)))
                 (custom-function
                  ;; call custom function if defined
                  (funcall custom-function))
-- 
2.38.1.420.g319605f8f0