Subject: bug#54967: 28.1; outline-minor-mode-cycle-filter docstring is awkward

From: Howard Melman <[email-masked]>
Date: Fri, 15 Apr 2022 20:04:40 -0400

The docstring of outline-minor-mode-cycle-filter says it
filters out positions available for cycling.  But the
options the user has (via customize) describe the places on
the heading that will remain for cycling.

(defcustom outline-minor-mode-cycle-filter nil
  "Filter out positions on the heading available for cycling."
  :type '(choice (const :tag "Everywhere" nil)
                 (const :tag "At line beginning" bolp)
                 (const :tag "Not at line beginning"
                        (lambda () (not (bolp))))
                 (const :tag "At line end" eolp)
                 (function :tag "Custom filter"))
  :version "28.1")

E.g., if I choose "At line beginning" then cycling works if
point is at the beginning of line.  But the doc sounds to
me like it shouldn't work at that location.

Maybe it should be something like:

    "Allowed heading positions available for cycling."

And I think it should probably mention that this means other
positions in the heading are allowed for indenting or
tabbing, but I'm not sure how to phrase that in a way that
works if people rebind commands to different keys.

Howard

In GNU Emacs 28.1 (build 1, x86_64-apple-darwin20.6.0, Carbon Version 164 AppKit 2022.6)
of 2022-04-09 built on Mac-1649520554451.local
Repository revision: ee79b048bbb2fd4a962dfb2204cc7a2f0d5237d8
Repository branch: 28.1-mac-9.0-CI
Windowing system distributor 'Apple Inc.', version 11.6.5
System Description:  macOS 11.6.5