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

Previous Next

Full log

Message #17 received at 72405 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Visuwesh <visuweshm <at> gmail.com>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 72405 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#72405: 29.4; Doc string of `org-indent-mode'
Date: Thu, 01 Aug 2024 09:18:11 +0300

> From: Visuwesh <visuweshm <at> gmail.com>
> Cc: 72405 <at> debbugs.gnu.org,  Drew Adams <drew.adams <at> 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 <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)))

Stefan, any comments to this suggestion?

Previous Next

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