Re: Extend Outline mode with default visibility state

Re: Extend Outline mode with default visibility state

[Eli Zaretskii]

The doc string of outline-default-state "Needs Work":

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

What major mode does this allude to?

  When nil, headings visibility is left unchanged.

Unchanged from what state?

  If equal to `outline-show-all', all text of buffer is shown.

  If equal to `outline-show-only-headings', only headings are shown.

What does "headings" mean here?  Does it mean headings off all the
levels, or just of the top level, or something else?

  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.

Is `outline-default-rules' relevant only to that single value of
outline-default-state?

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

This doesn't say whether the function is called with any arguments.

The doc string of outline-default-rules also "Needs Work":

  (defcustom outline-default-rules nil
    "Determines visibility of subtree starting at `outline-default-state' level.

If this is only relevant to a single value of outline-default-state,
the doc string should say so.

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

This should tell what arguments, if any, the function is called.
Also, "function ... will be evaluated" is not our style.

Can these issues be fixed, please?

Thanks.

Re: Extend Outline mode with default visibility state

[Eli Zaretskii]

> Date: Sun, 16 Jan 2022 20:42:07 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> The doc string of outline-default-rules also "Needs Work":
> 
>   (defcustom outline-default-rules nil
>     "Determines visibility of subtree starting at `outline-default-state' level.
> 
> If this is only relevant to a single value of outline-default-state,
> the doc string should say so.
> 
>   - 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."
> 
> This should tell what arguments, if any, the function is called.
> Also, "function ... will be evaluated" is not our style.

In addition, the "A lambda function or function name" part seems to be
incorrect: it should be a cons cell of the form

  (custom-function FUNCTION)

Right?

Re: Extend Outline mode with default visibility state

[Matthias Meulien]

Eli Zaretskii <eliz@gnu.org> writes:

> (...)  In addition, the "A lambda function or function name" part
> seems to be incorrect: it should be a cons cell of the form
>
>   (custom-function FUNCTION)
>
> Right?

Yes, you're right.  A fixed this in the proposed doc strings patch.
-- 
Matthias

Re: Extend Outline mode with default visibility state

[Stefan Monnier]

>> (...)  In addition, the "A lambda function or function name" part
>> seems to be incorrect: it should be a cons cell of the form

BTW, I'd go with just "a function", as in something which satisfies
`functionp`.


        Stefan

Re: Extend Outline mode with default visibility state

[Matthias Meulien]

[-- Attachment #1: Type: text/plain, Size: 304 bytes --]

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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-some-doc-strings-in-outline.el.patch --]
[-- Type: text/x-diff, Size: 3143 bytes --]

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


[-- Attachment #3: Type: text/plain, Size: 194 bytes --]


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

Re: Extend Outline mode with default visibility state

[Eli Zaretskii]

> From: Matthias Meulien <orontee@gmail.com>
> Cc: Juri Linkov <juri@linkov.net>,  emacs-devel@gnu.org
> Date: Mon, 17 Jan 2022 20:34:38 +0100
> 
> Here is a patch where I tried to improve the doc strings.

Thanks, these updates are fine by me.

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

It's a mild joke: where I would normally use a much stronger words, I
use that instead to appear more polite.

Re: Extend Outline mode with default visibility state

[Matthias Meulien]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Matthias Meulien <orontee@gmail.com>
>> Cc: Juri Linkov <juri@linkov.net>,  emacs-devel@gnu.org
>> Date: Mon, 17 Jan 2022 20:34:38 +0100
>> 
>> Here is a patch where I tried to improve the doc strings.
>
> Thanks, these updates are fine by me.

Good! One will have to apply them to master, I don't have the needed
right access.

>> 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?
>
> It's a mild joke: where I would normally use a much stronger words, I
> use that instead to appear more polite.

Thanks for clarifying and sorry for being that clumsy in english.
-- 
Matthias

Re: Extend Outline mode with default visibility state

[Eli Zaretskii]

> From: Matthias Meulien <orontee@gmail.com>
> Cc: juri@linkov.net,  emacs-devel@gnu.org
> Date: Fri, 21 Jan 2022 21:54:25 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Matthias Meulien <orontee@gmail.com>
> >> Cc: Juri Linkov <juri@linkov.net>,  emacs-devel@gnu.org
> >> Date: Mon, 17 Jan 2022 20:34:38 +0100
> >> 
> >> Here is a patch where I tried to improve the doc strings.
> >
> > Thanks, these updates are fine by me.
> 
> Good! One will have to apply them to master, I don't have the needed
> right access.

Done.