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