GNU bug report logs - #57974
2022-08-30; Enhancing help facility for function doc string

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 57974 in the body.
You can then email your comments to 57974 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Ikumi Keita <ikumi <at> ikumi.que.jp>
To: bug-auctex <at> gnu.org
Subject: 2022-08-30; Enhancing help facility for function doc string
Date: Wed, 21 Sep 2022 18:25:44 +0900

This is a wishlist for record rather than a bug report. See
<URL:https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html> for the
background.

When a Elisp function A has :override advice B, help facility (C-h f)
displays doc string A, not B. It only indicates
This function has :override advice: THE-NAME-OF-B
modestly.

This is inconvenient, especially when A is a (major or minor) mode
function and the user typed C-h m in that mode buffer.

It would be worth considering to enhance the help facility to display
doc string of B instead when A is overrided by advice.

Regards,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine

Emacs  : GNU Emacs 28.2 (build 1, x86_64-unknown-freebsd13.1, GTK+ Version 3.24.33, cairo version 1.17.4)
 of 2022-09-15
Package: 2022-08-30

current state:
==============
(setq
 AUCTeX-date "2022-08-30"
 window-system 'x
 LaTeX-version "2e"
 TeX-style-path '("/usr/local/var/auctex"
		  "/usr/local/share/emacs/site-lisp/auctex/style"
		  "/home/keita/.emacs.d/auctex/auto"
		  "/home/keita/.emacs.d/auctex/style" "auto" "style")
 TeX-auto-save nil
 TeX-parse-self t
 TeX-master nil
 TeX-command-list '(("TeX"
		     "%(PDF)%(tex) %(file-line-error) %`%(extraopts) %S%(PDFout)%(mode)%' %(output-dir) %t"
		     TeX-run-TeX nil
		     (plain-tex-mode ams-tex-mode texinfo-mode) :help
		     "Run plain TeX")
		    ("LaTeX" "%`%l%(mode)%' %T" TeX-run-TeX nil
		     (latex-mode doctex-mode) :help "Run LaTeX")
		    ("Makeinfo" "makeinfo %(extraopts) %(o-dir) %t"
		     TeX-run-compile nil (texinfo-mode) :help
		     "Run Makeinfo with Info output")
		    ("Makeinfo HTML"
		     "makeinfo %(extraopts) %(o-dir) --html %t"
		     TeX-run-compile nil (texinfo-mode) :help
		     "Run Makeinfo with HTML output")
		    ("AmSTeX"
		     "amstex %(PDFout) %`%(extraopts) %S%(mode)%' %(output-dir) %t"
		     TeX-run-TeX nil (ams-tex-mode) :help "Run AMSTeX")
		    ("ConTeXt"
		     "%(cntxcom) --once --texutil %(extraopts) %(execopts)%t"
		     TeX-run-TeX nil (context-mode) :help "Run ConTeXt once")
		    ("ConTeXt Full" "%(cntxcom) %(extraopts) %(execopts)%t"
		     TeX-run-TeX nil (context-mode) :help
		     "Run ConTeXt until completion")
		    ("BibTeX" "%(bibtex) %s" TeX-run-BibTeX nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode context-mode)
		     :help "Run BibTeX")
		    ("Biber" "biber %(output-dir) %s" TeX-run-Biber nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Run Biber")
		    ("Texindex" "texindex %s.??" TeX-run-command nil
		     (texinfo-mode) :help "Run Texindex")
		    ("Texi2dvi" "%(PDF)texi2dvi %t" TeX-run-command nil
		     (texinfo-mode) :help "Run Texi2dvi or Texi2pdf")
		    ("View" "%V" TeX-run-discard-or-function t t :help
		     "Run Viewer")
		    ("Print" "%p" TeX-run-command t t :help "Print the file")
		    ("Queue" "%q" TeX-run-background nil t :help
		     "View the printer queue" :visible TeX-queue-command)
		    ("File" "%(o?)dvips %d -o %f " TeX-run-dvips t
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Generate PostScript file")
		    ("Dvips" "%(o?)dvips %d -o %f " TeX-run-dvips nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Convert DVI file to PostScript")
		    ("Dvipdfmx" "dvipdfmx -o %(O?pdf) %d" TeX-run-dvipdfmx nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Convert DVI file to PDF with dvipdfmx")
		    ("Ps2pdf" "ps2pdf %f %(O?pdf)" TeX-run-ps2pdf nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Convert PostScript file to PDF")
		    ("Glossaries" "makeglossaries %(d-dir) %s" TeX-run-command
		     nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Run makeglossaries to create glossary file")
		    ("Index" "%(makeindex) %s" TeX-run-index nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Run makeindex to create index file")
		    ("upMendex" "upmendex %(O?idx)" TeX-run-index t
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Run upmendex to create index file")
		    ("Xindy" "texindy %s" TeX-run-command nil
		     (plain-tex-mode latex-mode doctex-mode ams-tex-mode
		      texinfo-mode)
		     :help "Run xindy to create index file")
		    ("Check" "lacheck %s" TeX-run-compile nil (latex-mode)
		     :help "Check LaTeX file for correctness")
		    ("ChkTeX" "chktex -v6 %s" TeX-run-compile nil (latex-mode)
		     :help "Check LaTeX file for common mistakes")
		    ("Spell" "(TeX-ispell-document \"\")" TeX-run-function nil
		     t :help "Spell-check the document")
		    ("Clean" "TeX-clean" TeX-run-function nil t :help
		     "Delete generated intermediate files")
		    ("Clean All" "(TeX-clean t)" TeX-run-function nil t :help
		     "Delete generated intermediate and output files")
		    ("Other" "" TeX-run-command t t :help
		     "Run an arbitrary command")
		    )
 )

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

From: Ikumi Keita <ikumi <at> ikumi.que.jp>
To: 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30;
 Enhancing help facility for function doc string
Date: Wed, 21 Sep 2022 19:15:39 +0900

Oops, sorry. I sent to wrong address. I reassigned this from "auctex" to
"emacs".

>>>>> Ikumi Keita <ikumi <at> ikumi.que.jp> writes:
> This is a wishlist for record rather than a bug report. See
> <URL:https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html> for the
> background.

> When a Elisp function A has :override advice B, help facility (C-h f)
> displays doc string A, not B. It only indicates
> This function has :override advice: THE-NAME-OF-B
> modestly.

> This is inconvenient, especially when A is a (major or minor) mode
> function and the user typed C-h m in that mode buffer.

> It would be worth considering to enhance the help facility to display
> doc string of B instead when A is overrided by advice.

> Regards,
> Ikumi Keita
> #StandWithUkraine #StopWarInUkraine

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Ikumi Keita <ikumi <at> ikumi.que.jp>
Cc: 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30; Enhancing help facility for function doc
 string
Date: Wed, 21 Sep 2022 13:56:58 +0200

Ikumi Keita <ikumi <at> ikumi.que.jp> writes:

> This is a wishlist for record rather than a bug report. See
> <URL:https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html> for the
> background.
>
> When a Elisp function A has :override advice B, help facility (C-h f)
> displays doc string A, not B. It only indicates
> This function has :override advice: THE-NAME-OF-B
> modestly.
>
> This is inconvenient, especially when A is a (major or minor) mode
> function and the user typed C-h m in that mode buffer.
>
> It would be worth considering to enhance the help facility to display
> doc string of B instead when A is overrided by advice.

I'm not quite sure I follow your meaning here.

Do you have a complete recipe, starting from "emacs -Q", that displays
the problem?

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

From: Ikumi Keita <ikumi <at> ikumi.que.jp>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30;
 Enhancing help facility for function doc string
Date: Wed, 21 Sep 2022 23:21:20 +0900

Hi Lars,

>>>>> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> I'm not quite sure I follow your meaning here.

> Do you have a complete recipe, starting from "emacs -Q", that displays
> the problem?

1. Save the following file as /tmp/foo.el
----------------------------------------------------------------------
(defun func-A ()
  "doc string of A"
  nil)

(defun func-B ()
  "doc string of B"
  t)

(advice-add 'func-A :override #'func-B)
----------------------------------------------------------------------
2. emacs -Q -l /tmp/foo.el
3. Type C-h f func-A RET
4. Then *Help* buffer pops up and shows
----------------------------------------------------------------------
func-A is a Lisp function in ‘/tmp/foo.el’.

(func-A)

doc string of A

This function has :override advice: ‘func-B’.
----------------------------------------------------------------------
The function A behaves as if it were the function B by the nature of
:override advice, so the doc string of A is almost useless. The actual
behavior is described by the doc string of B.

Unfortunately, when A is a mode function and has a long doc string,
users can easily look over the line
This function has :override advice: ‘func-B’.
far downward in the *Help* buffer when they see the output of C-h m.
That results in that they miss the "true" mode description provided by
the doc string of B.

Stephan suggested that such situation can be improved as
,----
| Maybe the help facility should be more careful in how it builds the
| docstring when a function has an `:override` advice, indeed.
`----
, in https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html

Regards,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Ikumi Keita <ikumi <at> ikumi.que.jp>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30; Enhancing help facility for function doc
 string
Date: Thu, 22 Sep 2022 13:13:54 +0200

Ikumi Keita <ikumi <at> ikumi.que.jp> writes:

> The function A behaves as if it were the function B by the nature of
> :override advice, so the doc string of A is almost useless. The actual
> behavior is described by the doc string of B.
>
> Unfortunately, when A is a mode function and has a long doc string,
> users can easily look over the line
> This function has :override advice: ‘func-B’.
> far downward in the *Help* buffer when they see the output of C-h m.
> That results in that they miss the "true" mode description provided by
> the doc string of B.
>
> Stephan suggested that such situation can be improved as
> ,----
> | Maybe the help facility should be more careful in how it builds the
> | docstring when a function has an `:override` advice, indeed.
> `----
> , in https://lists.gnu.org/r/auctex-devel/2022-09/msg00046.html

Right, makes sense.  But there can be more than one advice -- would
moving just the :overrides to the front of the doc string solve the
problem?

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Ikumi Keita <ikumi <at> ikumi.que.jp>, 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30; Enhancing help facility for function doc
 string
Date: Thu, 22 Sep 2022 10:26:28 -0400

> Right, makes sense.  But there can be more than one advice -- would
> moving just the :overrides to the front of the doc string solve the
> problem?

It used to be there, so maybe that's a good solution, yes.


        Stefan

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

From: Ikumi Keita <ikumi <at> ikumi.que.jp>
To: Lars Ingebrigtsen <larsi <at> gnus.org>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30;
 Enhancing help facility for function doc string
Date: Fri, 23 Sep 2022 00:22:06 +0900

>>>>> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>> Right, makes sense.  But there can be more than one advice -- would
>> moving just the :overrides to the front of the doc string solve the
>> problem?

> It used to be there, so maybe that's a good solution, yes.

More radical approach would also be an option, i.e., to display doc
string of B instead of A; but I don't strongly insist.

Bye,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Ikumi Keita <ikumi <at> ikumi.que.jp>
Cc: Lars Ingebrigtsen <larsi <at> gnus.org>, 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30; Enhancing help facility for function doc
 string
Date: Thu, 22 Sep 2022 12:47:37 -0400

Ikumi Keita [2022-09-23 00:22:06] wrote:
>>>>>> Stefan Monnier <monnier <at> iro.umontreal.ca> writes:
>>> Right, makes sense.  But there can be more than one advice -- would
>>> moving just the :overrides to the front of the doc string solve the
>>> problem?
>> It used to be there, so maybe that's a good solution, yes.
> More radical approach would also be an option, i.e., to display doc
> string of B instead of A; but I don't strongly insist.

I don't have a strong opinion either.  I think the issue has more to do
about how to implement it (the info about advice is provided via the
same mechanism used for all kinds of other auxiliary info and is not
designed to distinguish those things that are more or less important,
it has a very limited flexibility right now).


        Stefan

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Ikumi Keita <ikumi <at> ikumi.que.jp>, 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30; Enhancing help facility for function doc
 string
Date: Fri, 23 Sep 2022 17:10:38 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> I don't have a strong opinion either.  I think the issue has more to do
> about how to implement it (the info about advice is provided via the
> same mechanism used for all kinds of other auxiliary info and is not
> designed to distinguish those things that are more or less important,
> it has a very limited flexibility right now).

Today, I think the display is something along the lines of:

---
func-A is a Lisp function in /tmp/foo.el.

(func-A)

doc string of A

This function has :after advice: func-D.
This function has :before advice: func-C.
This function has :override advice: func-B.
---

Moving the :override line to the start would be easy enough, but should
perhaps also be rephrased to something like:

---
This function has :override advice: func-B, so func-A isn't run at all,
and the documentation below is possibly irrelevant.  See the
documentation to func-B instead.
---

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

From: Ikumi Keita <ikumi <at> ikumi.que.jp>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30;
 Enhancing help facility for function doc string
Date: Sat, 24 Sep 2022 15:04:04 +0900

Hi Lars,

>>>>> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> Moving the :override line to the start would be easy enough, but should
> perhaps also be rephrased to something like:

> ---
> This function has :override advice: func-B, so func-A isn't run at all,
> and the documentation below is possibly irrelevant.  See the
> documentation to func-B instead.
> ---

Thanks, I think the proposed stuff is organized well enough.

Regards,
Ikumi Keita
#StandWithUkraine #StopWarInUkraine

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Ikumi Keita <ikumi <at> ikumi.que.jp>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 57974 <at> debbugs.gnu.org
Subject: Re: bug#57974: 2022-08-30; Enhancing help facility for function doc
 string
Date: Sat, 24 Sep 2022 14:06:41 +0200

Ikumi Keita <ikumi <at> ikumi.que.jp> writes:

> Thanks, I think the proposed stuff is organized well enough.

I've now done this in Emacs 29.

Previous Next

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