Re: Extend Outline mode with default visibility state

[Matthias Meulien]

Eli Zaretskii <eliz@gnu.org> writes:

Thanks for your careful reading!

> The doc string of outline-default-state "Needs Work":
> (...)
> The doc string of outline-default-rules also "Needs Work":
> (...)
>
> Can these issues be fixed, please?

Here is a patch where I tried to improve the doc strings.

>From 9c5763b490b6cc482ea5467c7432a140750164e6 Mon Sep 17 00:00:00 2001
From: Matthias Meulien <orontee@gmail.com>
Date: Mon, 17 Jan 2022 20:20:28 +0100
Subject: [PATCH] Fix some doc strings in outline.el

* lisp/outline.el (outline-default-state): Fix doc string.
(outline-default-rules): Fix doc string.
---
 lisp/outline.el | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/lisp/outline.el b/lisp/outline.el
index 8e4af64370..4dbbaa26a0 100644
--- a/lisp/outline.el
+++ b/lisp/outline.el
@@ -1308,23 +1308,25 @@ outline-headers-as-kill
 (defcustom outline-default-state nil
   "If non-nil, some headings are initially outlined.
 
-Note that the default state is applied when the major mode is set
-or when the command `outline-apply-default-state' is called
-interactively.
+Note that the default state is applied when Outline major and
+minor modes are set or when the command
+`outline-apply-default-state' is called interactively.
 
-When nil, headings visibility is left unchanged.
+When nil, no default state is defined and
+`outline-apply-default-state' is a no-op.
 
 If equal to `outline-show-all', all text of buffer is shown.
 
-If equal to `outline-show-only-headings', only headings are shown.
+If equal to `outline-show-only-headings', show only headings,
+whatever their level is.
 
 If equal to a number, show only headings up to and including the
 corresponding level.  See `outline-default-rules' to customize
-visibility of the subtree at the choosen level.
+visibility of the subtree at that level.
 
 If equal to a lambda function or function name, this function is
-expected to toggle headings visibility, and will be called after
-the mode is enabled."
+expected to toggle headings visibility, and will be
+called without arguments after the mode is enabled."
   :version "29.1"
   :type '(choice (const :tag "Disabled" nil)
                  (const :tag "Show all" outline-show-all)
@@ -1335,6 +1337,9 @@ outline-default-state
 (defcustom outline-default-rules nil
   "Determines visibility of subtree starting at `outline-default-state' level.
 
+The rules apply if and only if `outline-default-state' is a
+number.
+
 When nil, the subtree is hidden unconditionally.
 
 When equal to a list, each element should be one of the following:
@@ -1350,10 +1355,11 @@ outline-default-rules
 - `subtree-is-long' to only show the heading branches when its
   subtree contains more than `outline-default-line-count' lines.
 
-- A lambda function or function name which will be evaluated with
-  point at the beginning of the heading and the match data set
-  appropriately, the function being expected to toggle the
-  heading visibility."
+- 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."
   :version "29.1"
   :type '(choice (const :tag "Hide subtree" nil)
                  (set :tag "Show subtree unless"
-- 
2.30.2

Just curious, what is the precise meaning of the quotes and
capitalization in your usage of "Needs Work", I am not a native English
speaker and I don't know how to interpret them?
-- 
Matthias