emacs-28 9da744e450: Fix documentation of Outline minor mode options

[Eli Zaretskii]

branch: emacs-28
commit 9da744e45021648a37f175967b536b151fd18750
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Fix documentation of Outline minor mode options
    
    * lisp/outline.el (outline-minor-mode-cycle-filter)
    (outline-minor-mode-cycle, outline-minor-mode-highlight)
    (outline-cycle, outline-cycle-buffer): Doc fixes.  (Bug#54967)
---
 lisp/outline.el | 73 ++++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 49 insertions(+), 24 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index ac51b53de3..00a557ca4e 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -176,13 +176,22 @@ in the file it applies to.")
     map))
 
 (defcustom outline-minor-mode-cycle-filter nil
-  "Filter out positions on the heading available for cycling."
+  "Control where on a heading the visibility-cycling commands are bound to 
keys.
+This option controls, in Outline minor mode, where on a heading typing
+the key sequences bound to visibility-cycling commands like `outline-cycle'
+and `outline-cycle-buffer' will invoke those commands.  By default, you can
+invoke these commands by typing `TAB' and `S-TAB' anywhere on a heading line,
+but customizing this option can make those bindings be in effect only at
+specific positions on the heading, like only at the line's beginning or
+line's end.  This allows these keys to be bound to their usual commands,
+as determined by the major mode, elsewhere on the heading lines.
+This option is only in effect when `outline-minor-mode-cycle' is non-nil."
   :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"))
+                 (function :tag "Custom filter function"))
   :version "28.1")
 
 (defun outline-minor-mode-cycle--bind (map key binding &optional filter)
@@ -349,28 +358,33 @@ After that, changing the prefix key requires manipulating 
keymaps."
          (set-default sym val)))
 
 (defcustom outline-minor-mode-cycle nil
-  "Enable cycling of headings in `outline-minor-mode'.
-When enabled, it puts a keymap with cycling keys on heading lines.
-When point is on a heading line, then typing `TAB' cycles between `hide all',
-`headings only' and `show all' (`outline-cycle').  Typing `S-TAB' on
-a heading line cycles the whole buffer (`outline-cycle-buffer').
-Typing these keys anywhere outside heading lines uses their default bindings."
+  "Enable visibility-cycling commands on headings in `outline-minor-mode'.
+If enabled, typing `TAB' on a heading line cycles the visibility
+state of that heading's body between `hide all', `headings only'
+and `show all' (`outline-cycle'), and typing `S-TAB' on a heading
+line likewise cycles the visibility state of the whole buffer
+\(`outline-cycle-buffer').
+Typing these keys anywhere outside heading lines invokes their default
+bindings, per the current major mode."
   :type 'boolean
   :version "28.1")
 ;;;###autoload(put 'outline-minor-mode-cycle 'safe-local-variable 'booleanp)
 
 (defcustom outline-minor-mode-highlight nil
-  "Highlight headings in `outline-minor-mode' using font-lock keywords.
-Non-nil value works well only when outline font-lock keywords
-don't conflict with the major mode's font-lock keywords.
-When t, it puts outline faces only if there are no major mode's faces
-on headings.  When `override', it completely overwrites major mode's
-faces with outline faces.  When `append', it tries to append outline
-faces to major mode's faces."
-  :type '(choice (const :tag "No highlighting" nil)
-                 (const :tag "Overwrite major mode faces" override)
-                 (const :tag "Append outline faces to major mode faces" append)
-                 (const :tag "Highlight separately from major mode faces" t))
+  "Whether to highlight headings in `outline-minor-mode' using font-lock 
keywords.
+This option controles whether `outline-minor-mode' will use its font-lock
+keywords to highlight headings, which could potentially conflict with
+font-lock faces defined by the major mode.  Thus, a non-nil value will
+work well only when there's no such conflict.
+If the value is t, use outline faces only if there are no major mode's
+font-lock faces on headings.  When `override', completely overwrite major
+mode's font-lock faces with outline faces.  When `append', try to append
+outline font-lock faces to those of major mode."
+  :type '(choice (const :tag "Do not use outline font-lock highlighting" nil)
+                 (const :tag "Overwrite major mode font-lock faces" override)
+                 (const :tag "Append outline font-lock faces to major mode's"
+                        append)
+                 (const :tag "Highlight with outline font-lock faces only if 
major mode doesn't" t))
   :version "28.1")
 ;;;###autoload(put 'outline-minor-mode-highlight 'safe-local-variable 'symbolp)
 
@@ -1244,11 +1258,14 @@ Return either 'hide-all, 'headings-only, or 'show-all."
        (save-excursion (outline-end-of-subtree) (point)))))
 
 (defun outline-cycle ()
-  "Cycle between `hide all', `headings only' and `show all'.
+  "Cycle visibility state of the current heading line's body.
 
-`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."
+This cycles the visibility of the current heading line's subheadings
+and body between `hide all', `headings only' and `show all'.
+
+`Hide all' means hide all the subheadings and their bodies.
+`Headings only' means show the subheadings, but not their bodies.
+`Show all' means show all the subheadings and their bodies."
   (interactive)
   (condition-case nil
       (pcase (outline--cycle-state)
@@ -1270,7 +1287,15 @@ Return either 'hide-all, 'headings-only, or 'show-all."
   "Internal variable used for tracking buffer cycle state.")
 
 (defun outline-cycle-buffer ()
-  "Cycle the whole buffer like in `outline-cycle'."
+  "Cycle visibility state of the body lines of the whole buffer.
+
+This cycles the visibility of all the subheadings and bodies of all
+the heading lines in the buffer.  It cycles them between `hide all',
+`headings only' and `show all'.
+
+`Hide all' means hide all the buffer's subheadings and their bodies.
+`Headings only' means show all the subheadings, but not their bodies.
+`Show all' means show all the buffer's subheadings and their bodies."
   (interactive)
   (let (has-top-level)
     (save-excursion