bug#72405: 29.4; Doc string of `org-indent-mode'

bug#72405: 29.4; Doc string of `org-indent-mode'

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Likely applies also to other minor-mode doc strings.

emacs -Q
C-h f org-indent-mode
____

That shows you doc that includes this, where `org-indent-mode' is a link
intended to give you information about the _variable_ of that name:

  To check whether the minor mode is enabled in the current buffer,
  evaluate 'org-indent-mode'.

Clicking that link doesn't take you to the _variable_ part of the *Help*
buffer; it just puts you back at the start of the buffer (after
redrawing it uselessly).

It should take you to the description of the variable.  And the sentence
should include the word "variable" before `org-indent-mode'; otherwise,
it makes little sense to speak of evaluating that symbol, and the text
can confuse or mislead users.


In GNU Emacs 29.4 (build 2, x86_64-w64-mingw32) of 2024-07-05 built on
 AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.4651)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation=aot
 --without-compress-install --with-sqlite3 --with-tree-sitter
 CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

Important settings:
  value of $LANG: ENU
  locale-coding-system: cp1252

bug#72405: 29.4; Doc string of `org-indent-mode'

[Eli Zaretskii]

> Date: Wed, 31 Jul 2024 20:23:59 +0000
> From:  Drew Adams via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Likely applies also to other minor-mode doc strings.
> 
> emacs -Q
> C-h f org-indent-mode
> ____
> 
> That shows you doc that includes this, where `org-indent-mode' is a link
> intended to give you information about the _variable_ of that name:
> 
>   To check whether the minor mode is enabled in the current buffer,
>   evaluate 'org-indent-mode'.
> 
> Clicking that link doesn't take you to the _variable_ part of the *Help*
> buffer; it just puts you back at the start of the buffer (after
> redrawing it uselessly).
> 
> It should take you to the description of the variable.  And the sentence
> should include the word "variable" before `org-indent-mode'; otherwise,
> it makes little sense to speak of evaluating that symbol, and the text
> can confuse or mislead users.

Thanks, but please report Org issues to the Org mailing list first.
If the Org developers determine it's a core Emacs problem (which is
hardly possible in this case, but who knows?), then it should be
reported here.

bug#72405: 29.4; Doc string of `org-indent-mode'

[Visuwesh]

[வியாழன் ஆகஸ்ட் 01, 2024] Eli Zaretskii wrote:

>> Date: Wed, 31 Jul 2024 20:23:59 +0000
>> From:  Drew Adams via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> Likely applies also to other minor-mode doc strings.
>> 
>> emacs -Q
>> C-h f org-indent-mode
>> ____
>> 
>> That shows you doc that includes this, where `org-indent-mode' is a link
>> intended to give you information about the _variable_ of that name:
>> 
>>   To check whether the minor mode is enabled in the current buffer,
>>   evaluate 'org-indent-mode'.
>> 
>> Clicking that link doesn't take you to the _variable_ part of the *Help*
>> buffer; it just puts you back at the start of the buffer (after
>> redrawing it uselessly).
>> 
>> It should take you to the description of the variable.  And the sentence
>> should include the word "variable" before `org-indent-mode'; otherwise,
>> it makes little sense to speak of evaluating that symbol, and the text
>> can confuse or mislead users.
>
> Thanks, but please report Org issues to the Org mailing list first.
> If the Org developers determine it's a core Emacs problem (which is
> hardly possible in this case, but who knows?), then it should be
> reported here.

That sentence is part of easy-mmode--arg-docstring that gets added to
all the minor-mode docstrings.  So it is not org-mode specific.  For
example, font-lock-mode also has the following text:

    To check whether the minor mode is enabled in the current buffer,
    evaluate ‘font-lock-mode’.

bug#72405: 29.4; Doc string of `org-indent-mode'

[Visuwesh]

[வியாழன் ஆகஸ்ட் 01, 2024] Visuwesh wrote:

> [வியாழன் ஆகஸ்ட் 01, 2024] Eli Zaretskii wrote:
>
>>> Date: Wed, 31 Jul 2024 20:23:59 +0000
>>> From:  Drew Adams via "Bug reports for GNU Emacs,
>>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>>> 
>>> Likely applies also to other minor-mode doc strings.
>>> 
>>> emacs -Q
>>> C-h f org-indent-mode
>>> ____
>>> 
>>> That shows you doc that includes this, where `org-indent-mode' is a link
>>> intended to give you information about the _variable_ of that name:
>>> 
>>>   To check whether the minor mode is enabled in the current buffer,
>>>   evaluate 'org-indent-mode'.
>>> 
>>> Clicking that link doesn't take you to the _variable_ part of the *Help*
>>> buffer; it just puts you back at the start of the buffer (after
>>> redrawing it uselessly).
>>> 
>>> It should take you to the description of the variable.  And the sentence
>>> should include the word "variable" before `org-indent-mode'; otherwise,
>>> it makes little sense to speak of evaluating that symbol, and the text
>>> can confuse or mislead users.
>>
>> Thanks, but please report Org issues to the Org mailing list first.
>> If the Org developers determine it's a core Emacs problem (which is
>> hardly possible in this case, but who knows?), then it should be
>> reported here.
>
> That sentence is part of easy-mmode--arg-docstring that gets added to
> all the minor-mode docstrings.  So it is not org-mode specific.  For
> example, font-lock-mode also has the following text:
>
>     To check whether the minor mode is enabled in the current buffer,
>     evaluate ‘font-lock-mode’.

Here's a patch to make it insert "the variable " after evaluate.  But
I'm not sure if (symbolp getter) will catch all non-variable cases.
AFAIU, GETTER can be any generalised variable.

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index ba0f8bad393..2262fb8ed5b 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -91,7 +91,7 @@ easy-mmode--arg-docstring
 Disable the mode if ARG is a negative number.
 
 To check whether the minor mode is enabled in the current buffer,
-evaluate `%s'.
+evaluate %s`%s'.
 
 The mode's hook is called both when the mode is enabled and when
 it is disabled.")
@@ -128,6 +128,7 @@ easy-mmode--mode-docstring
                         easy-mmode--arg-docstring
                         (if global "global " "")
                         mode-pretty-name
+                        (if (symbolp getter) "the variable " "")
                         ;; Avoid having quotes turn into pretty quotes.
                         (string-replace "'" "\\='" (format "%S" getter)))))
           (let ((start (point)))

bug#72405: 29.4; Doc string of `org-indent-mode'

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: 72405@debbugs.gnu.org,  Drew Adams <drew.adams@oracle.com>
> Date: Thu, 01 Aug 2024 11:29:12 +0530
> 
> [வியாழன் ஆகஸ்ட் 01, 2024] Visuwesh wrote:
> 
> > [வியாழன் ஆகஸ்ட் 01, 2024] Eli Zaretskii wrote:
> >
> >>> Date: Wed, 31 Jul 2024 20:23:59 +0000
> >>> From:  Drew Adams via "Bug reports for GNU Emacs,
> >>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> >>> 
> >>> Likely applies also to other minor-mode doc strings.
> >>> 
> >>> emacs -Q
> >>> C-h f org-indent-mode
> >>> ____
> >>> 
> >>> That shows you doc that includes this, where `org-indent-mode' is a link
> >>> intended to give you information about the _variable_ of that name:
> >>> 
> >>>   To check whether the minor mode is enabled in the current buffer,
> >>>   evaluate 'org-indent-mode'.
> >>> 
> >>> Clicking that link doesn't take you to the _variable_ part of the *Help*
> >>> buffer; it just puts you back at the start of the buffer (after
> >>> redrawing it uselessly).
> >>> 
> >>> It should take you to the description of the variable.  And the sentence
> >>> should include the word "variable" before `org-indent-mode'; otherwise,
> >>> it makes little sense to speak of evaluating that symbol, and the text
> >>> can confuse or mislead users.
> >>
> >> Thanks, but please report Org issues to the Org mailing list first.
> >> If the Org developers determine it's a core Emacs problem (which is
> >> hardly possible in this case, but who knows?), then it should be
> >> reported here.
> >
> > That sentence is part of easy-mmode--arg-docstring that gets added to
> > all the minor-mode docstrings.  So it is not org-mode specific.  For
> > example, font-lock-mode also has the following text:
> >
> >     To check whether the minor mode is enabled in the current buffer,
> >     evaluate ‘font-lock-mode’.
> 
> Here's a patch to make it insert "the variable " after evaluate.  But
> I'm not sure if (symbolp getter) will catch all non-variable cases.
> AFAIU, GETTER can be any generalised variable.
> 
> diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
> index ba0f8bad393..2262fb8ed5b 100644
> --- a/lisp/emacs-lisp/easy-mmode.el
> +++ b/lisp/emacs-lisp/easy-mmode.el
> @@ -91,7 +91,7 @@ easy-mmode--arg-docstring
>  Disable the mode if ARG is a negative number.
>  
>  To check whether the minor mode is enabled in the current buffer,
> -evaluate `%s'.
> +evaluate %s`%s'.
>  
>  The mode's hook is called both when the mode is enabled and when
>  it is disabled.")
> @@ -128,6 +128,7 @@ easy-mmode--mode-docstring
>                          easy-mmode--arg-docstring
>                          (if global "global " "")
>                          mode-pretty-name
> +                        (if (symbolp getter) "the variable " "")
>                          ;; Avoid having quotes turn into pretty quotes.
>                          (string-replace "'" "\\='" (format "%S" getter)))))
>            (let ((start (point)))

Stefan, any comments to this suggestion?

bug#72405: 29.4; Doc string of `org-indent-mode'

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

>> Here's a patch to make it insert "the variable " after evaluate.  But
>> I'm not sure if (symbolp getter) will catch all non-variable cases.
>> AFAIU, GETTER can be any generalised variable.
[...]
> Stefan, any comments to this suggestion?

Looks OK to me.


        Stefan

bug#72405: 29.4; Doc string of `org-indent-mode'

[Visuwesh]

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

[செவ்வாய் ஆகஸ்ட் 13, 2024] Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" wrote:

>>> Here's a patch to make it insert "the variable " after evaluate.  But
>>> I'm not sure if (symbolp getter) will catch all non-variable cases.
>>> AFAIU, GETTER can be any generalised variable.
> [...]
>> Stefan, any comments to this suggestion?
>
> Looks OK to me.
>
>
>         Stefan

Thanks, so I've attached a properly formatted patch.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Disambiguate-minor-mode-variable-in-its-function-doc.patch --]
[-- Type: text/x-diff, Size: 1472 bytes --]

From 535ae70653745f529742993f7fc26daf00666713 Mon Sep 17 00:00:00 2001
From: Visuwesh <visuweshm@gmail.com>
Date: Wed, 14 Aug 2024 08:07:15 +0530
Subject: [PATCH] Disambiguate minor-mode variable in its function docstring

* lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring)
(easy-mmode--mode-docstring): Add "the variable" before the
GETTER if it is a symbol to properly link to minor-mode variable
in the *Help* buffer in the common case.  (bug#72405)
---
 lisp/emacs-lisp/easy-mmode.el | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 944a74a91ee..5332a3b4fcf 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -91,7 +91,7 @@ easy-mmode--arg-docstring
 Disable the mode if ARG is a negative number.
 
 To check whether the minor mode is enabled in the current buffer,
-evaluate `%s'.
+evaluate %s`%s'.
 
 The mode's hook is called both when the mode is enabled and when
 it is disabled.")
@@ -128,6 +128,7 @@ easy-mmode--mode-docstring
                         easy-mmode--arg-docstring
                         (if global "global " "")
                         mode-pretty-name
+                        (if (symbolp getter) "the variable " "")
                         ;; Avoid having quotes turn into pretty quotes.
                         (string-replace "'" "\\='" (format "%S" getter)))))
           (let ((start (point)))
-- 
2.45.2

bug#72405: 29.4; Doc string of `org-indent-mode'

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  72405@debbugs.gnu.org,
>   drew.adams@oracle.com
> Date: Wed, 14 Aug 2024 08:09:20 +0530
> 
> Thanks, so I've attached a properly formatted patch.
> 
> 
> >From 535ae70653745f529742993f7fc26daf00666713 Mon Sep 17 00:00:00 2001
> From: Visuwesh <visuweshm@gmail.com>
> Date: Wed, 14 Aug 2024 08:07:15 +0530
> Subject: [PATCH] Disambiguate minor-mode variable in its function docstring
> 
> * lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring)
> (easy-mmode--mode-docstring): Add "the variable" before the
> GETTER if it is a symbol to properly link to minor-mode variable
> in the *Help* buffer in the common case.  (bug#72405)
> ---
>  lisp/emacs-lisp/easy-mmode.el | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
> index 944a74a91ee..5332a3b4fcf 100644
> --- a/lisp/emacs-lisp/easy-mmode.el
> +++ b/lisp/emacs-lisp/easy-mmode.el
> @@ -91,7 +91,7 @@ easy-mmode--arg-docstring
>  Disable the mode if ARG is a negative number.
>  
>  To check whether the minor mode is enabled in the current buffer,
> -evaluate `%s'.
> +evaluate %s`%s'.
            ^^^^^
This looks like a bug (I know it isn't, but it looks like one).  Can
we instead use just %s here, and generate the full string, including
the "the variable" part, in the code that uses the format?

Thanks.

bug#72405: 29.4; Doc string of `org-indent-mode'

[Visuwesh]

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

[புதன் ஆகஸ்ட் 14, 2024] Eli Zaretskii wrote:

>> diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
>> index 944a74a91ee..5332a3b4fcf 100644
>> --- a/lisp/emacs-lisp/easy-mmode.el
>> +++ b/lisp/emacs-lisp/easy-mmode.el
>> @@ -91,7 +91,7 @@ easy-mmode--arg-docstring
>>  Disable the mode if ARG is a negative number.
>>  
>>  To check whether the minor mode is enabled in the current buffer,
>> -evaluate `%s'.
>> +evaluate %s`%s'.
>             ^^^^^
> This looks like a bug (I know it isn't, but it looks like one).  Can
> we instead use just %s here, and generate the full string, including
> the "the variable" part, in the code that uses the format?
>
> Thanks.

Is the attached patch fine?  


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Disambiguate-minor-mode-variable-in-its-function-doc.patch --]
[-- Type: text/x-diff, Size: 1815 bytes --]

From 335e30093d9d5b08f8ef4473b86e89c1a3175e9c Mon Sep 17 00:00:00 2001
From: Visuwesh <visuweshm@gmail.com>
Date: Wed, 14 Aug 2024 08:07:15 +0530
Subject: [PATCH] Disambiguate minor-mode variable in its function docstring

* lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring)
(easy-mmode--mode-docstring): Add "the variable" before the
GETTER if it is a symbol to properly link to minor-mode variable
in the *Help* buffer in the common case.  (bug#72405)
---
 lisp/emacs-lisp/easy-mmode.el | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 944a74a91ee..96bab8487b4 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -91,7 +91,7 @@ easy-mmode--arg-docstring
 Disable the mode if ARG is a negative number.
 
 To check whether the minor mode is enabled in the current buffer,
-evaluate `%s'.
+evaluate %s.
 
 The mode's hook is called both when the mode is enabled and when
 it is disabled.")
@@ -128,8 +128,11 @@ easy-mmode--mode-docstring
                         easy-mmode--arg-docstring
                         (if global "global " "")
                         mode-pretty-name
-                        ;; Avoid having quotes turn into pretty quotes.
-                        (string-replace "'" "\\='" (format "%S" getter)))))
+                        (concat
+                         (when (symbolp getter) "the variable ")
+                         (format "`%s'"
+                                 ;; Avoid having quotes turn into pretty quotes.
+                                 (string-replace "'" "\\='" (format "%S" getter)))))))
           (let ((start (point)))
             (insert argdoc)
             (when (fboundp 'fill-region) ;Don't break bootstrap!
-- 
2.45.2

bug#72405: 29.4; Doc string of `org-indent-mode'

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: monnier@iro.umontreal.ca,  72405@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Wed, 14 Aug 2024 12:08:33 +0530
> 
> >> +evaluate %s`%s'.
> >             ^^^^^
> > This looks like a bug (I know it isn't, but it looks like one).  Can
> > we instead use just %s here, and generate the full string, including
> > the "the variable" part, in the code that uses the format?
> >
> > Thanks.
> 
> Is the attached patch fine?  

Yes, but please use 'if' rather than 'when'.

bug#72405: 29.4; Doc string of `org-indent-mode'

[Visuwesh]

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

[புதன் ஆகஸ்ட் 14, 2024] Eli Zaretskii wrote:

>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: monnier@iro.umontreal.ca,  72405@debbugs.gnu.org,  drew.adams@oracle.com
>> Date: Wed, 14 Aug 2024 12:08:33 +0530
>> 
>> >> +evaluate %s`%s'.
>> >             ^^^^^
>> > This looks like a bug (I know it isn't, but it looks like one).  Can
>> > we instead use just %s here, and generate the full string, including
>> > the "the variable" part, in the code that uses the format?
>> >
>> > Thanks.
>> 
>> Is the attached patch fine?  
>
> Yes, but please use 'if' rather than 'when'.

Sorry, but I'm confused.  I used 'when' because 

    (concat nil "xxx") ;; => "xxx"

But if you don't want to rely on this implicit behaviour, I turned the
'when' to 'if' in the attached patch.  I hope this is what you meant.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Disambiguate-minor-mode-variable-in-its-function-doc.patch --]
[-- Type: text/x-diff, Size: 1816 bytes --]

From b390ad167f82c7e0d449437f9e464dde9ef799a4 Mon Sep 17 00:00:00 2001
From: Visuwesh <visuweshm@gmail.com>
Date: Wed, 14 Aug 2024 08:07:15 +0530
Subject: [PATCH] Disambiguate minor-mode variable in its function docstring

* lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring)
(easy-mmode--mode-docstring): Add "the variable" before the
GETTER if it is a symbol to properly link to minor-mode variable
in the *Help* buffer in the common case.  (bug#72405)
---
 lisp/emacs-lisp/easy-mmode.el | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 944a74a91ee..7a014e164bd 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -91,7 +91,7 @@ easy-mmode--arg-docstring
 Disable the mode if ARG is a negative number.
 
 To check whether the minor mode is enabled in the current buffer,
-evaluate `%s'.
+evaluate %s.
 
 The mode's hook is called both when the mode is enabled and when
 it is disabled.")
@@ -128,8 +128,11 @@ easy-mmode--mode-docstring
                         easy-mmode--arg-docstring
                         (if global "global " "")
                         mode-pretty-name
-                        ;; Avoid having quotes turn into pretty quotes.
-                        (string-replace "'" "\\='" (format "%S" getter)))))
+                        (concat
+                         (if (symbolp getter) "the variable " "")
+                         (format "`%s'"
+                                 ;; Avoid having quotes turn into pretty quotes.
+                                 (string-replace "'" "\\='" (format "%S" getter)))))))
           (let ((start (point)))
             (insert argdoc)
             (when (fboundp 'fill-region) ;Don't break bootstrap!
-- 
2.45.2

bug#72405: 29.4; Doc string of `org-indent-mode'

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: monnier@iro.umontreal.ca,  72405@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Wed, 14 Aug 2024 12:57:17 +0530
> 
> >> Is the attached patch fine?  
> >
> > Yes, but please use 'if' rather than 'when'.
> 
> Sorry, but I'm confused.  I used 'when' because 
> 
>     (concat nil "xxx") ;; => "xxx"

Yes, of course.  But 'if' also returns nil if its condition is false:

  (if (symbolp 1) "symbol")
   => nil

So you can still use the original code, which uses the above behavior
of 'concat', after replacing 'when' with 'if' in your original code.

The reason I asked to use 'if' is that there's no reason to use 'when'
here, as the BODY of 'when' will only ever be a single string.

bug#72405: 29.4; Doc string of `org-indent-mode'

[Visuwesh]

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

[புதன் ஆகஸ்ட் 14, 2024] Eli Zaretskii wrote:

>> From: Visuwesh <visuweshm@gmail.com>
>> Cc: monnier@iro.umontreal.ca,  72405@debbugs.gnu.org,  drew.adams@oracle.com
>> Date: Wed, 14 Aug 2024 12:57:17 +0530
>> 
>> >> Is the attached patch fine?  
>> >
>> > Yes, but please use 'if' rather than 'when'.
>> 
>> Sorry, but I'm confused.  I used 'when' because 
>> 
>>     (concat nil "xxx") ;; => "xxx"
>
> Yes, of course.  But 'if' also returns nil if its condition is false:
>
>   (if (symbolp 1) "symbol")
>    => nil
>
> So you can still use the original code, which uses the above behavior
> of 'concat', after replacing 'when' with 'if' in your original code.
>
> The reason I asked to use 'if' is that there's no reason to use 'when'
> here, as the BODY of 'when' will only ever be a single string.

Ah, I understand now.  I find using 'if' without the else-clause
confusing when glancing at the code so I opted to use 'when'.  Thanks
for taking your time to explain what you meant.  Attached patch replaces
'when' with 'if'.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Disambiguate-minor-mode-variable-in-its-function-doc.patch --]
[-- Type: text/x-diff, Size: 1813 bytes --]

From b9e134f25f7767223fe8d482a9a3b27281180b1b Mon Sep 17 00:00:00 2001
From: Visuwesh <visuweshm@gmail.com>
Date: Wed, 14 Aug 2024 08:07:15 +0530
Subject: [PATCH] Disambiguate minor-mode variable in its function docstring

* lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring)
(easy-mmode--mode-docstring): Add "the variable" before the
GETTER if it is a symbol to properly link to minor-mode variable
in the *Help* buffer in the common case.  (bug#72405)
---
 lisp/emacs-lisp/easy-mmode.el | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 944a74a91ee..a140027839e 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -91,7 +91,7 @@ easy-mmode--arg-docstring
 Disable the mode if ARG is a negative number.
 
 To check whether the minor mode is enabled in the current buffer,
-evaluate `%s'.
+evaluate %s.
 
 The mode's hook is called both when the mode is enabled and when
 it is disabled.")
@@ -128,8 +128,11 @@ easy-mmode--mode-docstring
                         easy-mmode--arg-docstring
                         (if global "global " "")
                         mode-pretty-name
-                        ;; Avoid having quotes turn into pretty quotes.
-                        (string-replace "'" "\\='" (format "%S" getter)))))
+                        (concat
+                         (if (symbolp getter) "the variable ")
+                         (format "`%s'"
+                                 ;; Avoid having quotes turn into pretty quotes.
+                                 (string-replace "'" "\\='" (format "%S" getter)))))))
           (let ((start (point)))
             (insert argdoc)
             (when (fboundp 'fill-region) ;Don't break bootstrap!
-- 
2.45.2

bug#72405: 29.4; Doc string of `org-indent-mode'

[Eli Zaretskii]

> From: Visuwesh <visuweshm@gmail.com>
> Cc: monnier@iro.umontreal.ca,  72405@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Wed, 14 Aug 2024 13:34:18 +0530
> 
> > The reason I asked to use 'if' is that there's no reason to use 'when'
> > here, as the BODY of 'when' will only ever be a single string.
> 
> Ah, I understand now.  I find using 'if' without the else-clause
> confusing when glancing at the code so I opted to use 'when'.  Thanks
> for taking your time to explain what you meant.  Attached patch replaces
> 'when' with 'if'.

Thanks, installed on the emacs-30 branch, and closing the bug.