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

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

[Robert Pluim]

>>>>> On Mon, 24 Apr 2023 07:42:19 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:
 
    Eli> +(defcustom describe-bindings-outline-rules '((match-regexp . "Key translations"))
    Eli> +  "Visibility rules for outlines in the output buffer of `describe-bindings'.
    Eli> +This is used as the value of `outline-default-rules' in the
    Eli> +output buffer of `describe-bindings' when
    Eli> +`describe-bindings-outline' is non-nil, otherwise this option
    Eli> +doesn't have any effect."
    Eli> +  :type 'boolean
    Eli> +  :group 'help
    Eli> +  :version "30.1")
    Eli> +

That doesnʼt look like a boolean to me :-)

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Eshel Yaron <me@eshelyaron.com>
> Date: Mon, 24 Apr 2023 15:08:45 +0200
> 
> >>>>> On Mon, 24 Apr 2023 07:42:19 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:
>  
>     Eli> +(defcustom describe-bindings-outline-rules '((match-regexp . "Key translations"))
>     Eli> +  "Visibility rules for outlines in the output buffer of `describe-bindings'.
>     Eli> +This is used as the value of `outline-default-rules' in the
>     Eli> +output buffer of `describe-bindings' when
>     Eli> +`describe-bindings-outline' is non-nil, otherwise this option
>     Eli> +doesn't have any effect."
>     Eli> +  :type 'boolean
>     Eli> +  :group 'help
>     Eli> +  :version "30.1")
>     Eli> +
> 
> That doesnʼt look like a boolean to me :-)

Fixed, I hope.  Thanks.

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

[Robert Pluim]

>>>>> On Mon, 24 Apr 2023 19:24:20 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Cc: Eshel Yaron <me@eshelyaron.com>
    >> Date: Mon, 24 Apr 2023 15:08:45 +0200
    >> 
    >> >>>>> On Mon, 24 Apr 2023 07:42:19 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:
    >> 
    Eli> +(defcustom describe-bindings-outline-rules '((match-regexp . "Key translations"))
    Eli> +  "Visibility rules for outlines in the output buffer of `describe-bindings'.
    Eli> +This is used as the value of `outline-default-rules' in the
    Eli> +output buffer of `describe-bindings' when
    Eli> +`describe-bindings-outline' is non-nil, otherwise this option
    Eli> +doesn't have any effect."
    Eli> +  :type 'boolean
    Eli> +  :group 'help
    Eli> +  :version "30.1")
    Eli> +
    >> 
    >> That doesnʼt look like a boolean to me :-)

    Eli> Fixed, I hope.  Thanks.

Looks good (although Iʼm often torn between whether to use type 'radio
for these kinds of things).

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: emacs-devel@gnu.org,  me@eshelyaron.com
> Date: Mon, 24 Apr 2023 18:45:24 +0200
> 
> >>>>> On Mon, 24 Apr 2023 19:24:20 +0300, Eli Zaretskii <eliz@gnu.org> said:
> 
>     >> From: Robert Pluim <rpluim@gmail.com>
>     >> Cc: Eshel Yaron <me@eshelyaron.com>
>     >> Date: Mon, 24 Apr 2023 15:08:45 +0200
>     >> 
>     >> >>>>> On Mon, 24 Apr 2023 07:42:19 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:
>     >> 
>     Eli> +(defcustom describe-bindings-outline-rules '((match-regexp . "Key translations"))
>     Eli> +  "Visibility rules for outlines in the output buffer of `describe-bindings'.
>     Eli> +This is used as the value of `outline-default-rules' in the
>     Eli> +output buffer of `describe-bindings' when
>     Eli> +`describe-bindings-outline' is non-nil, otherwise this option
>     Eli> +doesn't have any effect."
>     Eli> +  :type 'boolean
>     Eli> +  :group 'help
>     Eli> +  :version "30.1")
>     Eli> +
>     >> 
>     >> That doesnʼt look like a boolean to me :-)
> 
>     Eli> Fixed, I hope.  Thanks.
> 
> Looks good (although Iʼm often torn between whether to use type 'radio
> for these kinds of things).

Feel free to change the forms there, I'm not wedded to what I did.

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

[Robert Pluim]

>>>>> On Mon, 24 Apr 2023 21:34:48 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> Looks good (although Iʼm often torn between whether to use type 'radio
    >> for these kinds of things).

    Eli> Feel free to change the forms there, I'm not wedded to what I did.

If I change it here, I have to change `outline-default-rules' to
match, and itʼs just not worth the effort for such minor point.

Robert
-- 

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

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > That doesnʼt look like a boolean to me :-)
>
> Fixed, I hope.  Thanks.

Thanks, too.

+                      (cons :tag "Custom function returns non-nil"
+                            (const custom-function) function)))

AFAIU this tag is misleading, though: `outline-default-rules's doc tells
that "[...] the function being expected to toggle the heading
visibility."  Specifying a predicate functions doesn't suffice.

Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Tue, 25 Apr 2023 03:13:40 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> +                      (cons :tag "Custom function returns non-nil"
> +                            (const custom-function) function)))
> 
> AFAIU this tag is misleading, though: `outline-default-rules's doc tells
> that "[...] the function being expected to toggle the heading
> visibility."  Specifying a predicate functions doesn't suffice.

Feel free to suggest a better tag, TIA.  Bonus points for untangling
the IMNSHO confusing documentation of outline-default-rules in these
areas (e.g., what does "function is expected to toggle the heading
visibility" even mean??) and fixing that and the related tags as well.
I simply had no time for that, sorry, and saying just "Custom
function" without any hint what that function should do seemed like a
bad idea.

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

[Robert Pluim]

>>>>> On Tue, 25 Apr 2023 09:45:36 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Michael Heerdegen <michael_heerdegen@web.de>
    >> Date: Tue, 25 Apr 2023 03:13:40 +0200
    >> 
    >> Eli Zaretskii <eliz@gnu.org> writes:
    >> 
    >> +                      (cons :tag "Custom function returns non-nil"
    >> +                            (const custom-function) function)))
    >> 
    >> AFAIU this tag is misleading, though: `outline-default-rules's doc tells
    >> that "[...] the function being expected to toggle the heading
    >> visibility."  Specifying a predicate functions doesn't suffice.

    Eli> Feel free to suggest a better tag, TIA.  Bonus points for untangling
    Eli> the IMNSHO confusing documentation of outline-default-rules in these
    Eli> areas (e.g., what does "function is expected to toggle the heading
    Eli> visibility" even mean??) and fixing that and the related tags as well.
    Eli> I simply had no time for that, sorry, and saying just "Custom
    Eli> function" without any hint what that function should do seemed like a
    Eli> bad idea.

The custom function is just funcallʼed, which is somewhat unfriendly,
since it forces the user to understand the details of how to hide
headings, which are not documented (what happens if the custom
function does nothing?). A predicate function would be more useful.

This code and the defcustom is new in emacs-29, so we can still change
it to be a predicate instead. At least we should document is better

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Michael Heerdegen <michael_heerdegen@web.de>,  emacs-devel@gnu.org,
>  Matthias Meulien <orontee@gmail.com>
> Date: Tue, 25 Apr 2023 10:25:51 +0200
> 
> >>>>> On Tue, 25 Apr 2023 09:45:36 +0300, Eli Zaretskii <eliz@gnu.org> said:
> 
>     Eli> Feel free to suggest a better tag, TIA.  Bonus points for untangling
>     Eli> the IMNSHO confusing documentation of outline-default-rules in these
>     Eli> areas (e.g., what does "function is expected to toggle the heading
>     Eli> visibility" even mean??) and fixing that and the related tags as well.
>     Eli> I simply had no time for that, sorry, and saying just "Custom
>     Eli> function" without any hint what that function should do seemed like a
>     Eli> bad idea.
> 
> The custom function is just funcallʼed, which is somewhat unfriendly,
> since it forces the user to understand the details of how to hide
> headings, which are not documented (what happens if the custom
> function does nothing?). A predicate function would be more useful.
> 
> This code and the defcustom is new in emacs-29, so we can still change
> it to be a predicate instead. At least we should document is better

Agreed.  Patches welcome.

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

[Robert Pluim]

>>>>> On Tue, 25 Apr 2023 12:09:58 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> This code and the defcustom is new in emacs-29, so we can still change
    >> it to be a predicate instead. At least we should document is better

    Eli> Agreed.  Patches welcome.

I assumed you were agreeing to the code change, which looks like this:

diff --git a/lisp/outline.el b/lisp/outline.el
index 0e90c59c285..266b3a168f6 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1517,10 +1517,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,9 +1533,9 @@ outline-default-rules
 
 - A cons cell of the form (custom-function . 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."
   :version "29.1"
   :type '(choice (const :tag "Hide subtree" nil)
                  (set :tag "Show subtree unless"
@@ -1649,9 +1650,10 @@ outline--show-headings-up-to-level
                  ;; show only branches when long lines are detected
                  ;; in subtree
                  (outline-show-branches))
-                (custom-function
-                 ;; call custom function if defined
-                 (funcall custom-function))
+                ;; call custom function if defined
+                ((and custom-function
+                      (funcall custom-function))
+                 (outline-hide-entry))
                 (t
                  ;; if no previous clause succeeds, show subtree
                  (outline-show-subtree))))))

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: michael_heerdegen@web.de,  emacs-devel@gnu.org,  orontee@gmail.com
> Date: Tue, 25 Apr 2023 12:11:57 +0200
> 
> >>>>> On Tue, 25 Apr 2023 12:09:58 +0300, Eli Zaretskii <eliz@gnu.org> said:
> 
>     >> This code and the defcustom is new in emacs-29, so we can still change
>     >> it to be a predicate instead. At least we should document is better
> 
>     Eli> Agreed.  Patches welcome.
> 
> I assumed you were agreeing to the code change, which looks like this:

No objections, unless some code is already using this with a function
that doesn't return a boolean.

Matthias, Juri: any objections or comments?

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

[Robert Pluim]

>>>>> On Tue, 25 Apr 2023 14:44:06 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> From: Robert Pluim <rpluim@gmail.com>
    >> Cc: michael_heerdegen@web.de,  emacs-devel@gnu.org,  orontee@gmail.com
    >> Date: Tue, 25 Apr 2023 12:11:57 +0200
    >> 
    >> >>>>> On Tue, 25 Apr 2023 12:09:58 +0300, Eli Zaretskii <eliz@gnu.org> said:
    >> 
    >> >> This code and the defcustom is new in emacs-29, so we can still change
    >> >> it to be a predicate instead. At least we should document is better
    >> 
    Eli> Agreed.  Patches welcome.
    >> 
    >> I assumed you were agreeing to the code change, which looks like this:

    Eli> No objections, unless some code is already using this with a function
    Eli> that doesn't return a boolean.

The only usage in-tree in emacs-29 is in `describe-bindings', where it
uses the `match-regexp' form.

Robert
-- 

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

[Juri Linkov]

>>     >> This code and the defcustom is new in emacs-29, so we can still change
>>     >> it to be a predicate instead. At least we should document is better
>> 
>>     Eli> Agreed.  Patches welcome.
>> 
>> I assumed you were agreeing to the code change, which looks like this:
>
> No objections, unless some code is already using this with a function
> that doesn't return a boolean.
>
> Matthias, Juri: any objections or comments?

I guess the decision was delegated to the users
because there is a choice what to do with the outline.
Beside 'outline-hide-entry', there is also 'outline-show-branches'
used by 'subtree-is-long' and 'subtree-has-long-lines'.

So I see no reason to remove 'custom-function'.
What could be done instead is to add a new choice
'custom-predicate'.

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

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Robert Pluim <rpluim@gmail.com>,  michael_heerdegen@web.de,
>   emacs-devel@gnu.org,  orontee@gmail.com
> Date: Tue, 25 Apr 2023 19:51:31 +0300
> 
> >>     >> This code and the defcustom is new in emacs-29, so we can still change
> >>     >> it to be a predicate instead. At least we should document is better
> >> 
> >>     Eli> Agreed.  Patches welcome.
> >> 
> >> I assumed you were agreeing to the code change, which looks like this:
> >
> > No objections, unless some code is already using this with a function
> > that doesn't return a boolean.
> >
> > Matthias, Juri: any objections or comments?
> 
> I guess the decision was delegated to the users
> because there is a choice what to do with the outline.
> Beside 'outline-hide-entry', there is also 'outline-show-branches'
> used by 'subtree-is-long' and 'subtree-has-long-lines'.
> 
> So I see no reason to remove 'custom-function'.
> What could be done instead is to add a new choice
> 'custom-predicate'.

The suggestion is not to remove custom-function.  The suggestion is to
require that the function returns a boolean, to mean whether to hide
or not to hide a heading, instead of requesting that the function
itself hides/unhides the headings.

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?

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

[Juri Linkov]

>> I guess the decision was delegated to the users
>> because there is a choice what to do with the outline.
>> Beside 'outline-hide-entry', there is also 'outline-show-branches'
>> used by 'subtree-is-long' and 'subtree-has-long-lines'.
>> 
>> So I see no reason to remove 'custom-function'.
>> What could be done instead is to add a new choice
>> 'custom-predicate'.
>
> The suggestion is not to remove custom-function.  The suggestion is to
> require that the function returns a boolean, to mean whether to hide
> or not to hide a heading, instead of requesting that the function
> itself hides/unhides the headings.
>
> 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?

How the user would be able to use 'outline-show-branches'
in the custom function, and not to use 'outline-hide-entry'?

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

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: rpluim@gmail.com,  michael_heerdegen@web.de,  emacs-devel@gnu.org,
>   orontee@gmail.com
> Date: Tue, 25 Apr 2023 20:35:04 +0300
> 
> >> I guess the decision was delegated to the users
> >> because there is a choice what to do with the outline.
> >> Beside 'outline-hide-entry', there is also 'outline-show-branches'
> >> used by 'subtree-is-long' and 'subtree-has-long-lines'.
> >> 
> >> So I see no reason to remove 'custom-function'.
> >> What could be done instead is to add a new choice
> >> 'custom-predicate'.
> >
> > The suggestion is not to remove custom-function.  The suggestion is to
> > require that the function returns a boolean, to mean whether to hide
> > or not to hide a heading, instead of requesting that the function
> > itself hides/unhides the headings.
> >
> > 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?
> 
> How the user would be able to use 'outline-show-branches'
> in the custom function, and not to use 'outline-hide-entry'?

Sorry, I don't understand the question and its relevance.  Maybe
Robert does.

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

[Robert Pluim]

>>>>> On Tue, 25 Apr 2023 21:00:08 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> >> So I see no reason to remove 'custom-function'.
    >> >> What could be done instead is to add a new choice
    >> >> 'custom-predicate'.
    >> >
    >> > The suggestion is not to remove custom-function.  The suggestion is to
    >> > require that the function returns a boolean, to mean whether to hide
    >> > or not to hide a heading, instead of requesting that the function
    >> > itself hides/unhides the headings.
    >> >
    >> > 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?
    >> 
    >> How the user would be able to use 'outline-show-branches'
    >> in the custom function, and not to use 'outline-hide-entry'?

    Eli> Sorry, I don't understand the question and its relevance.  Maybe
    Eli> Robert does.

In the current implementation, the user is free to write a function
that uses any of the outline-show/hide functions to get the effect
they desire. If we replace that with just a predicate function, then
theyʼre effectively restricted to `outline-hide-entry' and
`outline-show-subtree'.

I guess we could add `predicate', to be checked before
`custom-function', if set. If we do that, we definitely need to
document which outline functions are available. 100% backwards
compatible as well 😄

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Juri Linkov <juri@linkov.net>,  michael_heerdegen@web.de,
>   emacs-devel@gnu.org,  orontee@gmail.com
> Date: Wed, 26 Apr 2023 10:17:08 +0200
> 
> >>>>> On Tue, 25 Apr 2023 21:00:08 +0300, Eli Zaretskii <eliz@gnu.org> said:
> 
>     >> >> So I see no reason to remove 'custom-function'.
>     >> >> What could be done instead is to add a new choice
>     >> >> 'custom-predicate'.
>     >> >
>     >> > The suggestion is not to remove custom-function.  The suggestion is to
>     >> > require that the function returns a boolean, to mean whether to hide
>     >> > or not to hide a heading, instead of requesting that the function
>     >> > itself hides/unhides the headings.
>     >> >
>     >> > 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?
>     >> 
>     >> How the user would be able to use 'outline-show-branches'
>     >> in the custom function, and not to use 'outline-hide-entry'?
> 
>     Eli> Sorry, I don't understand the question and its relevance.  Maybe
>     Eli> Robert does.
> 
> In the current implementation, the user is free to write a function
> that uses any of the outline-show/hide functions to get the effect
> they desire. If we replace that with just a predicate function, then
> theyʼre effectively restricted to `outline-hide-entry' and
> `outline-show-subtree'.
> 
> I guess we could add `predicate', to be checked before
> `custom-function', if set. If we do that, we definitely need to
> document which outline functions are available. 100% backwards
> compatible as well 😄

Or maybe we stay with custom-function, but allow it to return symbols
other than nil and t, so it could, for example, return
'outline-show-branches'?

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

[Robert Pluim]

>>>>> On Wed, 26 Apr 2023 12:18:07 +0300, Eli Zaretskii <eliz@gnu.org> said:
    >> I guess we could add `predicate', to be checked before
    >> `custom-function', if set. If we do that, we definitely need to
    >> document which outline functions are available. 100% backwards
    >> compatible as well 😄

    Eli> Or maybe we stay with custom-function, but allow it to return symbols
    Eli> other than nil and t, so it could, for example, return
    Eli> 'outline-show-branches'?

That would work, but would mess up the hypothetical user who has
already written a custom-function without paying attention to its
return value.

Robert
-- 

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: juri@linkov.net,  michael_heerdegen@web.de,  emacs-devel@gnu.org,
>   orontee@gmail.com
> Date: Wed, 26 Apr 2023 12:01:14 +0200
> 
> >>>>> On Wed, 26 Apr 2023 12:18:07 +0300, Eli Zaretskii <eliz@gnu.org> said:
>     >> I guess we could add `predicate', to be checked before
>     >> `custom-function', if set. If we do that, we definitely need to
>     >> document which outline functions are available. 100% backwards
>     >> compatible as well 😄
> 
>     Eli> Or maybe we stay with custom-function, but allow it to return symbols
>     Eli> other than nil and t, so it could, for example, return
>     Eli> 'outline-show-branches'?
> 
> That would work, but would mess up the hypothetical user who has
> already written a custom-function without paying attention to its
> return value.

I thought we established there were no such users.

But I guess we could also ignore any unknown symbol the function
returns.

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

[Robert Pluim]

>>>>> On Wed, 26 Apr 2023 13:33:50 +0300, Eli Zaretskii <eliz@gnu.org> said:
    >> That would work, but would mess up the hypothetical user who has
    >> already written a custom-function without paying attention to its
    >> return value.

    Eli> I thought we established there were no such users.

No in-tree ones. There might be human ones

    Eli> But I guess we could also ignore any unknown symbol the function
    Eli> returns.

I donʼt see how that helps. A user function written with no regard to
return value is most likely to return nil or t, not a symbol.

Robert
-- 

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

[Michael Heerdegen]

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?

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

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

Michael.

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

[Robert Pluim]

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

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

[Michael Heerdegen]

Robert Pluim <rpluim@gmail.com> writes:

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

> -- 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.

Good idea - I like it.


[ BTW, this "accordingly set match data" is from `outline-map-region',
i.e. `outline-search-function' or (if nil) from matching outline-regexp?
Should we add that information? ]


Thanks,

Michael.

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

[Eshel Yaron]

Robert Pluim <rpluim@gmail.com> writes:

>>>>>> On Mon, 24 Apr 2023 07:42:19 -0400 (EDT), Eli Zaretskii <eliz@gnu.org> said:
>  
>     Eli> +(defcustom describe-bindings-outline-rules '((match-regexp . "Key translations"))
>     Eli> +  "Visibility rules for outlines in the output buffer of `describe-bindings'.
>     Eli> +This is used as the value of `outline-default-rules' in the
>     Eli> +output buffer of `describe-bindings' when
>     Eli> +`describe-bindings-outline' is non-nil, otherwise this option
>     Eli> +doesn't have any effect."
>     Eli> +  :type 'boolean
>     Eli> +  :group 'help
>     Eli> +  :version "30.1")
>     Eli> +
>
> That doesnʼt look like a boolean to me :-)

Oops, thank you for spotting my oversight.

> Robert

-- 
Eshel