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

[Visuwesh <visuweshm@gmail.com>]

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