GNU bug report logs - #72405
29.4; Doc string of `org-indent-mode'

Previous Next

Full log

View this message in rfc822 format

From: Visuwesh <visuweshm <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 72405 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: bug#72405: 29.4; Doc string of `org-indent-mode'
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 <at> 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)))

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.